Update an on-chain settlement address
PUT/payments/settlementChange 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
| Header | Description | Required |
|---|---|---|
| Authorization | Bearer token with your secret API key | yes |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| new_address | string | yes | |
| chain | string | yes |
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
| Status | Description |
|---|---|
| 200 | The updated settlement address and its on-chain nonce. |
| 400 | Validation error |
| 401 | Missing or invalid authentication |
| 403 | API key lacks the required scope |
| 504 | code: 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
| Field | Type | Required | Description |
|---|---|---|---|
| address | string | yes | |
| chain | string | yes | |
| nonce | number | yes | |
| tx_hash | string | yes |
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
