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"
  ]
}

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