Register or update a wallet

Upserts one wallet per tokenKey. An empty wallet string reserves the token before a real address is known and is never used as a payout destination. See Core concepts → Wallets.

Authorization

apiKey

X-API-Key<token>

Your merchant API key, shown once at creation in the dashboard (Settings → API key).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tokenKey*string

Which chain+token this wallet settles, as a catalog key from GET /v1/currencies. One registered wallet per token — posting the same tokenKey again replaces the address.

Value in

"usdc-polygon"
"usdt-polygon"
"usdc-arbitrum"
"usdt-arbitrum"
"usdc-base"
"eurc-base"
"usdc-optimism"
"usdt-optimism"
"usdc-base-sepolia"
"usdc-solana"
"usdt-solana"
"eurc-solana"
"usdc-solana-devnet"

wallet*string

Your payout address for this token. Must match the token's chain family (0x… for EVM, base58 for Solana). Once registered it OVERRIDES the merchantDestinationWallet on every offer using this token, retroactively — including offers created before it existed. Deleting it reverts to each offer's own address.

Response Body

`application/json`

curl -X POST "https://example.com/wallets" \  -H "Content-Type: application/json" \  -d '{    "tokenKey": "usdc-polygon",    "wallet": "0x71c7656ec7ab88b098defb751b7401b5f6d8976"  }'

{  "wallet": {    "id": "wal_01j8x2q3r4s5t6u7v8w9x0y1z2",    "merchantId": "string",    "tokenKey": "usdc-polygon",    "chainId": 137,    "receiverWallet": "0x71c7656ec7ab88b098defb751b7401b5f6d8976",    "createdAt": "2026-08-19T14:32:00.000Z"  }}

Register or update a wallet

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`