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.
💡
The nonce and factory address are managed by the API. Call GET /payments/settlement to retrieve current values before signing.
Headers
| Header | Description | Required |
|---|---|---|
| Authorization | Bearer token with your API key | yes |
| Content-Type | application/json | yes |
| X-Signature | Signature from signSettlementChange(), 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_id | number | The chain ID to update settlement for (e.g., 1 for Ethereum mainnet). | yes |
Example Request
import { signSettlementChange } from '@exodus/checkout-signer'
const newAddress = '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21'
const chainId = 1 // Ethereum mainnet
// First, fetch the current factory address and nonce for this chain
const settlementInfo = await fetch('https://checkout.exodus.com/payments/settlement', {
headers: { Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx' },
}).then((r) => r.json())
const { factory_address: factoryAddress, nonce } = settlementInfo.chains.find(
(c) => c.chain_id === chainId,
)
const signature = signSettlementChange(
factoryAddress,
newAddress,
nonce,
chainId,
process.env.SIGNING_PRIVATE_KEY,
)
const response = await fetch('https://checkout.exodus.com/payments/settlement', {
method: 'PUT',
headers: {
Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
'X-Signature': signature,
},
body: JSON.stringify({ new_address: newAddress, chain_id: chainId }),
})Response
SUCCESSFUL UPDATE
{
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
"chain_id": 1,
"nonce": 2,
"tx_hash": "0x8a9c67b2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9"
}Error Responses
INVALID SIGNATURE
{
"error": {
"type": "authentication_error",
"message": "Invalid signature"
}
}STALE NONCE
{
"error": {
"type": "invalid_request",
"message": "Nonce is stale — fetch the current nonce and try again"
}
}