Partners
Markdown

Set payout wallet, replace or restore a wallet

POST /api/v1/partner/customers/{customerId}/payout-wallets/{walletId}

Required scope: payout_wallets:write, plus the payout_wallets capability, an Idempotency-Key and a partner.payout_wallet signature.

set_payout — make this the payout wallet

{
  "action": "set_payout",
  "acknowledged": true
}

Moves is_payout_wallet to this wallet. Refused with 400 cooling_off while the wallet is inside its 24-hour cooling-off (see details[0].cooling_off_until). If it already is the payout wallet the response carries "unchanged": true.

replace — swap a wallet for a new address

{
  "action": "replace",
  "chain": "TRC20",
  "asset": "USDT",
  "address": "TNEW…",
  "label": "New USDT",
  "acknowledged": true
}

Archives {walletId} and adds the new wallet in one change. If the replaced wallet was the payout wallet, the new one takes over. The response carries the new wallet and archived_wallet_id.

An address the customer has held before is still in the book, so replace onto it answers 409 conflict rather than adding a second row. If the wallet holding it is archived, restore it and then set_payout; if it is active, set_payout on that wallet directly.

restore — bring an archived wallet back

{
  "action": "restore"
}

Returns an archived wallet to status: "active" with its original id, label and address. No acknowledgement, because nothing moves: is_payout_wallet is left alone, so a restored wallet becomes the payout destination only through a following set_payout. Refused with 400 invalid_request when the wallet is not archived, or when the customer already holds the maximum number of active wallets.

Errors

400 invalid_request (unknown action, validation, missing acknowledgement, wallet not archived, active-wallet cap), 400 cooling_off, 404 not_found, 409 conflict (the address is already in the book), 429 rate_limited, plus the common errors.