Update Settlement Address
PUT/payments/settlementDescription
Update the wallet address where captured payments are sent. This is a per-chain operation. To change settlement on multiple chains, call this endpoint once per chain with a separate signature for each.
Settlement address changes take effect immediately for all future captures.
Sign each change against the chain’s settlement contract_address and current nonce, both
returned by GET /payments/settlement below. The nonce starts at
0 and increments by one on each successful change. A stale nonce is rejected with the expected
value (see Error Responses), so you can re-sign without guessing.
Read the current settlement
GET/payments/settlementReturns the settlement contract_address and current nonce for every chain your business is configured on. Pass the entry for a chain straight into signSettlementChange (with the new_address you want) to sign the next change.
{
"settlements": [
{
"chain": "eip155:1",
"contract_address": "0xfaceb00cfaceb00cfaceb00cfaceb00cfaceb00c",
"nonce": 1
}
]
}Headers
| Header | Description | Required |
|---|---|---|
| Authorization | Bearer token with your API key | yes |
| Content-Type | application/json | yes |
| X-Signature | Signature from signSettlementChange() (EIP-712 typed data), signed with your signing key. | yes |
Request Body
| Name | Type | Description | Required |
|---|---|---|---|
| new_address | string | The new wallet address to receive captured payments. | yes |
| chain | string | The CAIP-2 chain identifier to update settlement for (e.g. "eip155:1"). | yes |
Example Request
import { CheckoutSigner } from '@exodus/checkout-signer'
const signer = new CheckoutSigner()
const chain = 'eip155:1' // CAIP-2 chain id (Ethereum mainnet)
const newAddress = '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21'
// Read the current settlement contract + nonce for the chain
const { settlements } = await fetch('https://checkout-api.exodus-int.com/payments/settlement', {
headers: { Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx' },
}).then((r) => r.json())
const current = settlements.find((s) => s.chain === chain)
if (!current) throw new Error(`No settlement configured for ${chain}`)
// Pass the read straight in; only new_address is yours to supply
const { signature, body } = signer.signSettlementChange({ ...current, new_address: newAddress })
const response = await fetch('https://checkout-api.exodus-int.com/payments/settlement', {
method: 'PUT',
headers: {
Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
'X-Signature': signature,
},
body: JSON.stringify(body),
})Response
{
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
"chain": "eip155:1",
"nonce": 2,
"tx_hash": "0x8a9c67b2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9"
}Error Responses
{
"error": {
"type": "authentication_error",
"message": "Invalid settlement signature"
}
}{
"error": {
"type": "cannot_process",
"message": "Settlement signature uses a stale nonce",
"code": "stale_nonce",
"data": {
"business_id": "qy7h2k9m4n8p3r5t6w1x",
"chain": "eip155:1",
"expected_nonce": 2
}
}
}If your signature was valid but against an out-of-date nonce, the API recognizes it and returns data.expected_nonce — re-sign against that value and retry.
