Recipients API

Use the recipients API to create or reuse saved payout destinations for private API workflows such as onramps.

POST /api/v1/recipients

Authentication

All recipient endpoints require your secret API key in the x-yara-api-key header.

x-yara-api-key: <secret-key>
Content-Type: application/json

Response Envelope

Successful responses use this envelope:

{
  "data": {},
  "message": "success"
}

Validation errors return:

{
  "error": "..."
}

Supported recipient types for onramps

The recipient API supports multiple recipient types across Yara, but onramps currently support these destination types:

YARA_TAG
CRYPTO_WALLET
USD_BANK_ACCOUNT

BANK_ACCOUNT recipients may exist elsewhere in the platform, but they are not valid onramp destinations.

Create a recipient

This endpoint is useful when you want to save a destination first and then reference it later with recipient_id when creating an onramp.

Create a YaraTag recipient

curl -X POST "https://api.yara.cash/api/v1/recipients" \
  -H "Content-Type: application/json" \
  -H "x-yara-api-key: <secret-key>" \
  -d '{
    "recipient_type": "YARA_TAG",
    "yara_tag": "$ayo",
    "beneficiary": true
  }'

Create a crypto wallet recipient

curl -X POST "https://api.yara.cash/api/v1/recipients" \
  -H "Content-Type: application/json" \
  -H "x-yara-api-key: <secret-key>" \
  -d '{
    "recipient_type": "CRYPTO_WALLET",
    "name": "Ada Base Wallet",
    "email": "[email protected]",
    "beneficiary": true,
    "crypto_details": {
      "token": "USDC",
      "chain": "BASE",
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
    }
  }'

Create a USD bank recipient

curl -X POST "https://api.yara.cash/api/v1/recipients" \
  -H "Content-Type: application/json" \
  -H "x-yara-api-key: <secret-key>" \
  -d '{
    "recipient_type": "USD_BANK_ACCOUNT",
    "name": "Ada Cooper",
    "email": "[email protected]",
    "beneficiary": true,
    "usd_bank_details": {
      "account_number": "123456789012",
      "routing_number": "021000021",
      "bank_name": "JPMorgan Chase Bank",
      "account_owner_name": "Ada Cooper",
      "street_line_1": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US",
      "checking_or_savings": "checking"
    }
  }'

Request fields

Common fields

Field	Type	Required	Notes
`recipient_type`	string	Yes	`YARA_TAG`, `CRYPTO_WALLET`, or `USD_BANK_ACCOUNT` for onramp use cases
`name`	string	Conditional	Required for crypto and USD bank recipients
`email`	string	Conditional	Required for crypto and USD bank recipients
`beneficiary`	boolean	No	Marks the recipient as a beneficiary
`yara_tag`	string	Conditional	Required for `YARA_TAG` recipients
`crypto_details`	object	Conditional	Required for `CRYPTO_WALLET` recipients
`usd_bank_details`	object	Conditional	Required for `USD_BANK_ACCOUNT` recipients

`crypto_details`

Field	Type	Required	Notes
`token`	string	Yes	Example: `USDC`
`chain`	string	Yes	Example: `BASE`
`address`	string	Yes	Destination wallet address

`usd_bank_details`

Field	Type	Required	Notes
`account_number`	string	Yes	Recipient bank account number
`routing_number`	string	Yes	US routing number
`bank_name`	string	Yes	Recipient bank name
`account_owner_name`	string	Yes	Legal account owner name
`street_line_1`	string	Yes	Street address
`city`	string	Yes	City
`state`	string	Yes	State or region
`postal_code`	string	Yes	Postal code
`country`	string	Yes	Country code, such as `US`
`checking_or_savings`	string	Yes	`checking` or `savings`

Response example

{
  "data": {
    "id": "8d3dc7d0-8db7-4e84-93e0-0c4d04802da4",
    "name": "Ada Base Wallet",
    "email": "[email protected]",
    "phone_number": "",
    "recipient_type": "CRYPTO_WALLET",
    "country": "NIGERIA",
    "bank_provider_type": "BANK",
    "beneficiary": true,
    "last_used_at": "2026-07-09T08:44:13Z",
    "crypto_details": {
      "token": "USDC",
      "chain": "BASE",
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
    }
  },
  "message": "success"
}

Notes

Crypto recipients are validated against Yara's supported token and chain combinations
USD bank recipients require the caller account to be enabled for USD bank payouts
YaraTag recipients may be created on demand from a YaraTag string
Saved recipients can be reused in the Onramps API with recipient_id