API reference
Save destination
Register the wallet that receives the merchant share.
PUT
/settlement-addressesRegister the wallet that receives the 99.01% share. Console admins only; API keys are rejected. The first wallet on a network is saved at once (200). Any later change returns 202: confirm it with the code emailed to you, then it takes effect after a 24-hour hold during which every member is emailed and any admin can cancel it. Issued invoices keep the wallet recorded when they were created.
- Permission
- organization admin
- Auth
- console
- Idempotent
- No
- Language
- Node.js
| Field | In | Type | Required | Description |
|---|---|---|---|---|
| label | body | string | Yes | Human-readable name shown in the console. |
| provider | body | string | Yes | personal or an exchange identifier. Exchange destinations are asset-specific. |
| chain | body | string | Yes | Network this address accepts. |
| tokenSymbol | body | string | Yes | Asset this destination accepts. Do not reuse an exchange ETH address for USDC. |
| address | body | string | Yes | Full receiving address. Every change is recorded with its actor. Keys that do not need to change destinations should not hold write:settlement. |
Console-only: needs a signed-in organization admin. API keys are rejected.
const response = await fetch(`${process.env.BOSPAY_API_BASE}/settlement-addresses`, {
method: "PUT",
headers: {
"Content-Type": "application/json",
"BOSPay-Version": "2026-09-23",
"Authorization": "Bearer CONSOLE_ACCESS_TOKEN",
},
body: JSON.stringify({
"label": "USDC treasury",
"provider": "personal",
"chain": "base",
"tokenSymbol": "USDC",
"address": "YOUR_RECEIVING_ADDRESS"
})
});
if (!response.ok) {
throw new Error(`BOSPay request failed: ${response.status}`);
}
const data = await response.json();Success
200
{
"object": "destination",
"id": "dest_example",
"chain": "base",
"tokenSymbol": "USDC",
"provider": "personal",
"address": "YOUR_RECEIVING_ADDRESS"
}Validation error
400
{
"error": {
"type": "invalid_request_error",
"code": "validation_error",
"message": "A valid fiatAmount is required.",
"field": "fiatAmount",
"requestId": "req_3f0c9a1b2c4d5e6f7a8b9c0d"
}
}