> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stabyl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Saved Recipients

> Create, list, update, and delete saved fiat and crypto 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 and crypto-recipient management is unchanged. Development
and staging skip the fiat-recipient KYB gate.

| Endpoint                                            | Purpose                   |
| --------------------------------------------------- | ------------------------- |
| `POST /partner/wallets/recipients`                  | Create a saved recipient  |
| `GET /partner/wallets/recipients`                   | List saved recipients     |
| `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

```bash theme={null}
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

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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",
    "created_at": "2026-07-17T12:00:00Z",
    "updated_at": "2026-07-17T12:00:00Z"
  }
}
```

## Recipient Types

| Type   | Typical fields                                         | Recommended validation                         |
| ------ | ------------------------------------------------------ | ---------------------------------------------- |
| Fiat   | bank code, account number, account name, display label | Verify account before saving                   |
| Crypto | asset rail, chain, address, display label              | Confirm route and address format before saving |

Use clear labels that operators can recognize in Stabyl Pro. Avoid labels that only make sense inside one internal service.

<Warning>
  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`.
</Warning>

## Update or delete a recipient

```bash theme={null}
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` enabled for recipient management. Common failures include a key that is not permitted for the action, invalid account details, duplicate recipient details, or a recipient identifier that does not exist.