Partners

Register a withdrawal wallet

POST /api/v1/partner/customers/{customerId}/withdrawal-wallets

Adds a destination to the customer’s withdrawal allowlist. The signature requirement makes this the real control that the withdrawal signature protects.

Request

curl -X POST https://api.niftipay.com/api/v1/partner/customers/{customerId}/withdrawal-wallets \
  -H "Authorization: Bearer <partner_api_key>" \
  -H "Idempotency-Key: <uuid>" \
  -H "X-Withdrawal-Signature: <ed25519-assertion>" \
  -H "Content-Type: application/json" \
  -d '{ "chain": "BTC", "asset": "BTC", "label": "Treasury", "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq", "destination_tag": "12345" }'
Field Type Required Notes
chain string yes One of BTC, ETH, LTC, SOL, XRP, TRON (uppercased).
asset string yes Uppercased.
label string yes Non-blank display label.
address string yes Must be valid for chain (typo guard).
destination_tag string no Optional; if present must be a non-blank string.

userId is set server-side from the relationship and ignored if supplied. At most 20 destinations may be registered per chain per customer.

Response 201

{
  "request_id": "req-1",
  "api_version": "2026-08-01",
  "data": {
    "wallet": {
      "id": "w-1",
      "chain": "BTC",
      "asset": "BTC",
      "label": "Treasury",
      "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
      "destination_tag": "12345",
      "created_at": "2026-08-24T10:00:00.000Z",
      "last_used_at": null
    }
  }
}

Errors

400 idempotency_key_required when no Idempotency-Key header is provided. 401 signature_required when X-Withdrawal-Signature is missing or invalid. 400 invalid_request for a non-JSON body or missing chain, asset, label, or address. 400 unsupported_chain when chain is not one of the six supported chains. 400 invalid_address when address is not valid for its chain. 409 wallet_limit_reached when 20 destinations already exist for this chain. 503 temporarily_unavailable for a transient database failure (reservation kept). 500 internal_error for a permanent write failure. 409 idempotency_key_reuse when the same key is reused with a different body. 409 idempotency_key_in_progress when retried inside the window after a transport failure.