Overview
Accounts
Beneficiaries
Create bank beneficiary
Create a bank beneficiary for an account.
curl --request POST \
--url https://api.nxos.io/v1/beneficiaries/bank \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"nickname": "Operating Account",
"bankName": "JPMorgan Chase",
"method": "WIRE",
"currency": "USD",
"swiftCode": "CHASUS33",
"accountNumber": "123456789",
"bankCountry": "US"
}
'{
"object": "beneficiary",
"beneficiaryId": "bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"type": "CRYPTO",
"nickname": "Treasury Wallet",
"status": "ACTIVE",
"entityType": "INDIVIDUAL",
"email": "[email protected]",
"phoneNumber": null,
"firstName": "John",
"lastName": "Doe",
"businessName": null,
"country": "US",
"crypto": {
"chainName": "ethereum",
"chainDisplayName": "Ethereum",
"platform": "EVM",
"address": "0x1234567890abcdef1234567890abcdef12345678"
},
"bank": null,
"createdAt": "2025-03-10T12:00:00.000Z"
}Headers
Bearer token. Format: Bearer <api_key>
Body
Request body for creating a bank beneficiary.
Account to register this beneficiary for.
Display name for the beneficiary.
Bank name.
Transfer method (e.g., WIRE, SEPA, ACH).
Payout currency code (e.g., USD, EUR).
SWIFT / BIC code.
Bank account number.
IBAN.
Routing number (US domestic).
Bank country (ISO 3166-1 alpha-2).
Bank address line 1.
Bank city.
Bank region / state.
Bank ZIP / postal code.
Intermediary bank name.
Intermediary SWIFT / BIC code.
Intermediary bank address.
Entity type.
INDIVIDUAL, BUSINESS Email address.
Phone number.
First name (individuals).
Last name (individuals).
Legal name.
Date of birth (YYYY-MM-DD).
Business name (businesses).
Registration / incorporation number.
Address line 1.
Address line 2.
City.
Region / state / province.
ZIP / postal code.
Country code (ISO 3166-1 alpha-2).
Tax ID.
Tax ID type (e.g., SSN, TIN).
Free-form tags (max 20 tags, each up to 100 characters).
Arbitrary metadata (max 50 keys, max 4 KB serialized).
Show child attributes
Show child attributes
Response
The request has succeeded.
A beneficiary (recipient) registered for payouts from an account.
All responses share this shape — the type field indicates which detail
object (crypto or bank) is populated; the other will be null.
Shared identity fields may be null in list and create responses.
Object type. Always beneficiary.
beneficiary Unique beneficiary identifier.
Account this beneficiary belongs to.
Beneficiary type.
CRYPTO, BANK Display name for the beneficiary.
Current status.
ACTIVE, INACTIVE, BLOCKED, ARCHIVED Entity type.
INDIVIDUAL, BUSINESS Email address.
Phone number.
First name (individuals).
Last name (individuals).
Business name (businesses).
Country code (ISO 3166-1 alpha-2).
Crypto-specific details. Present when type is CRYPTO, otherwise null.
Show child attributes
Show child attributes
Bank-specific details. Present when type is BANK, otherwise null.
Show child attributes
Show child attributes
When the beneficiary was created.
curl --request POST \
--url https://api.nxos.io/v1/beneficiaries/bank \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"nickname": "Operating Account",
"bankName": "JPMorgan Chase",
"method": "WIRE",
"currency": "USD",
"swiftCode": "CHASUS33",
"accountNumber": "123456789",
"bankCountry": "US"
}
'{
"object": "beneficiary",
"beneficiaryId": "bene_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"type": "CRYPTO",
"nickname": "Treasury Wallet",
"status": "ACTIVE",
"entityType": "INDIVIDUAL",
"email": "[email protected]",
"phoneNumber": null,
"firstName": "John",
"lastName": "Doe",
"businessName": null,
"country": "US",
"crypto": {
"chainName": "ethereum",
"chainDisplayName": "Ethereum",
"platform": "EVM",
"address": "0x1234567890abcdef1234567890abcdef12345678"
},
"bank": null,
"createdAt": "2025-03-10T12:00:00.000Z"
}