Saved Recipients

Saved recipients store reusable destination details for Stabyl Pro withdrawal workflows and account management. They are address book records, not payment instructions. Production requires approved KYB to create or update a fiat recipient. Recipient lists remain readable. In production, a crypto recipient’s address is screened when it is created or changed: an address that fails screening is rejected with 403 and never stored, and a screening outage returns 503. Development and staging skip both gates.

Endpoint	Purpose
`POST /partner/wallets/recipients`	Create a saved recipient
`GET /partner/wallets/recipients`	List saved recipients, optionally filtered by `recipient_type` (`fiat` or `crypto`) and `currency`
`PATCH /partner/wallets/recipients/{recipient_id}`	Update recipient metadata
`DELETE /partner/wallets/recipients/{recipient_id}`	Delete a saved recipient

Fiat recipient creation should follow account verification with POST /partner/wallets/fiat/verify-account. Crypto recipients are saved addresses and metadata only.

Create a fiat recipient

curl "$STABYL_BASE_URL/partner/wallets/recipients" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -d '{
    "recipient_type": "fiat",
    "label": "Operations account",
    "currency": "NGN",
    "bank_code": "044",
    "bank_name": "Access Bank",
    "account_number": "0123456789",
    "account_name": "Example Recipient"
  }'

Stabyl verifies the bank code and account number. Use the verified account name returned by the API rather than assuming the submitted name is authoritative.

Create a crypto recipient

curl "$STABYL_BASE_URL/partner/wallets/recipients" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -d '{
    "recipient_type": "crypto",
    "label": "Main USDT recipient",
    "currency": "USDT",
    "chain": "tron",
    "crypto_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "country": "NGA"
  }'

{
  "status": "success",
  "data": {
    "id": "0197f1f0-0000-7000-8000-000000000002",
    "recipient_type": "crypto",
    "label": "Main USDT recipient",
    "currency": "USDT",
    "chain": "tron",
    "bank_code": null,
    "bank_name": null,
    "account_number": null,
    "account_name": null,
    "crypto_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "country": "NGA",
    "status": "active",
    "created_at": "2026-07-17T12:00:00Z",
    "updated_at": "2026-07-17T12:00:00Z"
  }
}

Every recipient carries a status of active or suspended. Fiat recipients are always active. A crypto recipient becomes suspended if a later screening of its address fails, and returns to active automatically once a subsequent screening is clean. Do not offer a suspended recipient for selection.

Recipient Types

Type	Required fields	Must be absent	Recommended validation
Fiat	`currency`, `bank_code`, `account_number`, `account_name`, plus `label`	`chain`, `crypto_address`, `country`	Verify account before saving
Crypto	`chain` (`evm`, `tron`, or `solana`), `crypto_address`, plus `label` and optional `currency`, `country`	any bank or account field	Confirm route and address format before saving

The two field sets are strictly exclusive; mixing them returns 400. Unknown fields are rejected. country, when given, is an ISO 3166 alpha-3 code. Use clear labels that operators can recognize in Stabyl Pro. Avoid labels that only make sense inside one internal service.

Saved recipients do not initiate withdrawals through the API. Signed Partner withdrawal requests send destination details directly and do not accept a saved recipient_id.

Update or delete a recipient

curl "$STABYL_BASE_URL/partner/wallets/recipients/$RECIPIENT_ID" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -d '{"label": "Primary USDT recipient"}'

curl "$STABYL_BASE_URL/partner/wallets/recipients/$RECIPIENT_ID" \
  -X DELETE \
  -H "X-Api-Key: $STABYL_API_KEY"

Lifecycle

Action	Notes
Create	Store validated details for future use
List	Show current saved recipients for account review
Update	Change metadata or supported editable fields
Delete	Remove a saved recipient from future selection

Recipient routes require X-Api-Key with wallets:transfer. Common failures are 400 for invalid or mixed fields, 403 for a key without the scope, an account whose production KYB is not approved, or a crypto address that fails screening, 404 for an unknown recipient, 409 for a recipient with the same details as an existing one, and 503 when address screening is temporarily unavailable.

Get Started

Wallets

Exchange

Webhooks

WebSocket

Create a fiat recipient

Create a crypto recipient

Recipient Types

Update or delete a recipient

Lifecycle

​Create a fiat recipient

​Create a crypto recipient

​Recipient Types

​Update or delete a recipient

​Lifecycle

Create a fiat recipient

Create a crypto recipient

Recipient Types

Update or delete a recipient

Lifecycle