Skip to Content
CheckoutAPI ReferencePaymentsUpdate an on-chain settlement address

Update an on-chain settlement address

PUT/payments/settlement

Change the wallet address that captured funds settle to for a chain. Takes effect immediately for future captures. Requires a signed request (signSettlementChange()) against the chain's settlement contract and its current nonce, which increments on each successful change. A business has one settlement address across its EVM chains, so rotate every chain. Chains not rotated yet keep accepting subscription charges while their contract still pays the address recorded before this rotation; once every chain pays the new address, only the new address is accepted.

Headers

HeaderDescriptionRequired
AuthorizationBearer token with your secret API keyyes

Request Body

FieldTypeRequiredDescription
new_addressstringyes
chainstringyes

Example Request

Request

const response = await fetch('https://checkout-api.exodus.com/payments/settlement', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "new_address": "0xabcd1234abcd1234abcd1234abcd1234abcd1234",
    "chain": "eip155:1"
  }),
});

Responses

StatusDescription
200The updated settlement address and its on-chain nonce.
400Validation error
401Missing or invalid authentication
403API key lacks the required scope
504code: tx_pending: the settlement change was broadcast but the relay could not read its receipt within the wait (the wait timed out, or the RPC failed while polling). data carries chain and tx_hash. Do not resubmit: the new address is recorded within about 15 minutes after the transaction confirms. Until then, charges, captures and checkout subscribes on that chain may be refused with a 503 whose data.reason is settlement_address_mismatch, and new payments wait. Do not rotate again in that window, even though the 503 message says to. If the transaction reverts or never mines instead, the settlement address is not updated and you can send a new settlement request.

Response body

FieldTypeRequiredDescription
addressstringyes
chainstringyes
noncenumberyes
tx_hashstringyes

Example Response

{
  "address": "0xabcd1234abcd1234abcd1234abcd1234abcd1234",
  "chain": "eip155:1",
  "nonce": 2,
  "tx_hash": "0x8a9c67b2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9"
}

Error Response

Error (e.g. 400)

{
  "error": {
    "type": "validation_error",
    "message": "amount must be a positive number",
    "param": "amount"
  }
}
Last updated on

Start building

XO

Request Demo

Schedule a call with our team

Select a productArrow right

Start building
Grateful

Contact Us

We're here to help