Skip to main content
Ensure you have completed the steps from the quickstart guide in a separate terminal. This will set up your environment and spin up a bidder node.

​
Getting deposits and bidder balance

To query all deposits and your bidder’s balance on the mev-commit chain:
❯_ terminal
curl -s "http://localhost:13523/v1/bidder/get_all_deposits" | jq
❯_ typical response
{
"deposits": [
	{
	"provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
	"amount": "3000000000000000000"
	}
],
"bidderBalance": "9996999791340641239011"
}
Or to query a deposit specific to a single provider:
❯_ terminal
curl -s "http://localhost:13523/v1/bidder/get_deposit?provider=0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC" | jq
❯_ typical response
{
"amount": "0",
"provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC"
}
Deposit represents the funds in the bidder’s account that can be used to submit bids on the mev-commit p2p-network and settled on-chain.

​
Deposit manager

It’s recommended that bidders leverage the deposit manager to deposit, and automate ongoing re-deposits to specific providers. The deposit manager is an on-chain contract that a bidder account can enable by “setting their code” to the implementation using EIP-7702. After enabling the deposit manager, a bidder’s deposits are automatically replenished from the bidder’s EOA balance during the preconf settlement process, according to target deposit amounts configured by the bidder. A target deposit is the desired amount of funds that a bidder wants to be deposited for a specific provider. Bidders should set their target deposits to the maximum cumulative amount of ETH they would ever bid to a provider with respect to a single L1 block. If you followed the quickstart guide exactly, your bidder node will already have the deposit manager enabled. To confirm:

​
Get deposit manager status

❯_ terminal
curl -s http://localhost:13523/v1/bidder/deposit_manager_status | jq
❯_ typical response
{
  "enabled": true,
  "targetDeposits": [
    {
      "provider": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
      "targetDeposit": "3000000000000000000"
    }
  ]
}
There are two ways to enable the deposit manager… The easiest way to enable the deposit manager is by setting two flags/environment variables upon starting your bidder node:
❯_ terminal
mev-commit --enable-deposit-manager=true --target-deposit-amount=<amount>
Where the target deposit amount will be set for all valid providers that’re currently a part of the network. Alternatively you can use the MEV_COMMIT_ENABLE_DEPOSIT_MANAGER and MEV_COMMIT_TARGET_DEPOSIT_AMOUNT environment variables. This is the method used by the quickstart guide.

​
Enabling deposit manager through API

To enable the deposit manager through API, use the following command:
❯_ terminal
curl -s -X POST http://localhost:13523/v1/bidder/enable_deposit_manager | jq
❯_ typical response
{
  "success": true
}

​
Setting target deposits

Then to set target deposits customized to each provider:
❯_ terminal
curl -s -X POST http://localhost:13523/v1/bidder/set_target_deposits -H 'Content-Type: application/json' -d '{"target_deposits":[{"provider":"0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC","target_deposit":"3000000000000000000"}]}' | jq
❯_ typical response
{
  "successfullySetDeposits": [
    {
      "provider": "3c44cdddb6a900fa2b585dd299e03d12fa4293bc",
      "targetDeposit": "3000000000000000000"
    }
  ],
  "successfullyToppedUpProviders": [
    "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC"
  ]
}
You should be able to overwrite target deposits for providers at any time using the set_target_deposits endpoint.

​
Disable deposit manager

To disable the deposit manager call:
❯_ terminal
curl -X POST http://localhost:13523/v1/bidder/disable_deposit_manager | jq
❯_ typical response
{
  "success": true
}
This will set the bidder EOA’s code to zero address, effectively disabling the previous EIP-7702 delegation for the EOA.

​
Withdraw deposited funds

To withdraw funds from your deposit to a specific provider, use the following command:
❯_ terminal
curl -s -X POST http://localhost:13523/v1/bidder/request_withdrawals \
  -H 'Content-Type: application/json' \
  -d '{
    "providers": [
      "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC"
    ]
  }' | jq
❯_ typical response
{
  "providers": [
    "3c44cdddb6a900fa2b585dd299e03d12fa4293bc"
  ],
  "amounts": [
    "3000000000000000000"
  ]
}
Then you must wait the withdrawal period to elapse, currently ~10 minutes. Then finally call: 
curl -s -X POST http://localhost:13523/v1/bidder/withdraw \
  -H 'Content-Type: application/json' \
  -d '{
    "providers": [
      "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC"
    ]
  }' | jq
❯_ typical response
{
  "providers": [
    "3c44cdddb6a900fa2b585dd299e03d12fa4293bc"
  ],
  "amounts": [
    "3000000000000000000"
  ]
}

​
Querying valid providers

The valid providers endpoint can be used to get a list of all staked and fully registered providers.
❯_ terminal
curl -s http://localhost:13523/v1/bidder/get_valid_providers | jq
❯_ typical response
{
  "validProviders": [
    "0x88f231bcAa0384936121c31F3972D47F078784Ef"
  ]
}

​
Health

The health endpoint checks whether the bidder node is receiving events from mev-commit chain. This command is useful to determine whether the bidder node has become out of sync.
❯_ terminal
curl http://localhost:13523/health

​
Topology

The topology endpoint can be used to check which provider nodes the bidder node is connected to. It’ll also display your Ethereum Address and Peer Type.
❯_ terminal
curl http://localhost:13523/v1/debug/topology

​
Querying for proposers API

This API is enabled by default, the following environment variables could be set when launching a mev-commit client:
  • MEV_COMMIT_VALIDATOR_ROUTER_ADDR
  • MEV_COMMIT_BEACON_API_URL
  • MEV_COMMIT_L1_RPC_URL
Current address for the ValidatorOptInRouter contract on Hoodi is and on Mainnet is . The default URLs for the Mainnet Beacon Chain and L1 RPC are https://ethereum-beacon-api.publicnode.com and https://ethereum-rpc.publicnode.com, respectively, but you can set your own URLs. The default URLs for the Testnet Beacon Chain and L1 RPC are https://ethereum-hoodi-beacon-api.publicnode.com and https://ethereum-hoodi-rpc.publicnode.com, respectively, but you can set your own URLs. To get the information on whether validators for a specific epoch are opted in to mev-commit:
❯_ terminal
curl http://localhost:13523/v1/validator/get_validators?epoch=1
To get the information on whether validators for a latest epoch are opted in to mev-commit:
❯_ terminal
curl http://localhost:13523/v1/validator/get_validators
You can also subscribe to notifications to receive real-time updates when validators opt in or when a new epoch starts with opted-in validators. To subscribe to these notifications:
❯_ terminal
curl -N -H "Content-Type: application/json" -d '{"topics": ["validator_opted_in", "epoch_validators_opted_in"]}' http://localhost:13523/v1/subscribe
This will establish a streaming connection that will send notifications when:
  • The next block proposer has opted in to the mev-commit protocol (validator_opted_in)
  • A new epoch begins, providing a list of all opted-in validators for that epoch (epoch_validators_opted_in)
Note proposer selection is only stable within the context of the current epoch, and must be checked during the epoch in question. See specification here and here.

​
Configuring custom provider sets

Users can also set-up a specific subset of provider nodes in order to send their bids. By default the mev-commit bidder node will send bids to all the available and staked providers. However, if the user wants only a specific subset of providers to be able to see their bids, the can use the --provider-whitelist option to set it up. The list should contain the ethereum wallet addresses of the provider nodes.

​
Mainnet

❯_ terminal
mev-commit --keystore-path ~/.mev-commit \
 --keystore-password <PASSWORD> \
	--bootnodes /dnsaddr/bootnode.mev-commit.xyz \
	--settlement-rpc-endpoint https://chainrpc.mev-commit.xyz
  --provider-whitelist 0x6DcE7bcF4fCA9E14b546e583049B82474631b185,0x0979c194EaD08444B6e40415F5822AB32363f580

​
Testnet

❯_ terminal
mev-commit --keystore-path ~/.mev-commit \
 --keystore-password <PASSWORD> \
	--bootnodes /dnsaddr/bootnode.testnet.mev-commit.xyz \
	--settlement-rpc-endpoint https://chainrpc.testnet.mev-commit.xyz
  --provider-whitelist 0x6DcE7bcF4fCA9E14b546e583049B82474631b185,0x0979c194EaD08444B6e40415F5822AB32363f580
⌘I