Skip to main content
POST
/
v1
/
beneficiaries
/
nxosnet
cURL
curl --request POST \
  --url https://api.nxos.io/v1/beneficiaries/nxosnet \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "nickname": "Acme Corp",
  "targetHandle": "acme"
}
'
{
  "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",
  "addressLine1": null,
  "addressLine2": null,
  "city": null,
  "region": null,
  "zipCode": null,
  "crypto": {
    "chainName": "ethereum",
    "chainDisplayName": "Ethereum",
    "platform": "EVM",
    "address": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "bank": null,
  "nxosnet": null,
  "createdAt": "2025-03-10T12:00:00.000Z"
}

Headers

​
Authorization
string
required

Bearer token. Format: Bearer <api_key>

​
Idempotency-Key
string

Unique key per logical operation. UUID v4 recommended. Max 255 characters.

Body

application/json

Request body for creating an internal NXOS→NXOS beneficiary.

​
accountId
string
required

Account to register this beneficiary for.

​
nickname
string
required

Display name for the beneficiary.

​
targetHandle
string
required

The target organization's claimed nxosnet handle.

​
entityType
enum<string>

Entity type.

Available options:
INDIVIDUAL,
BUSINESS
​
email
string

Email address.

​
phoneNumber
string

Phone number.

​
firstName
string

First name (individuals).

​
lastName
string

Last name (individuals).

​
legalName
string

Legal name.

​
dateOfBirth
string

Date of birth (YYYY-MM-DD).

​
businessName
string

Business name (businesses).

​
registrationNumber
string

Registration / incorporation number.

​
addressLine1
string

Address line 1.

​
addressLine2
string

Address line 2.

​
city
string

City.

​
region
string

Region / state / province.

​
zipCode
string

ZIP / postal code.

​
country
string

Country code (ISO 3166-1 alpha-2).

​
taxId
string

Tax ID.

​
taxIdType
string

Tax ID type (e.g., SSN, TIN).

​
tags
string[]

Free-form tags (max 20 tags, each up to 100 characters).

​
metadata
object

Arbitrary metadata (max 50 keys, max 4 KB serialized).

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
enum<string>
required

Object type. Always beneficiary.

Available options:
beneficiary
​
beneficiaryId
string
required

Unique beneficiary identifier.

​
accountId
string
required

Account this beneficiary belongs to.

​
type
enum<string>
required

Beneficiary type.

Available options:
CRYPTO,
BANK,
NXOSNET
​
nickname
string
required

Display name for the beneficiary.

​
status
enum<string>
required

Current status.

Available options:
ACTIVE,
INACTIVE,
BLOCKED,
ARCHIVED
​
entityType
enum<string> | null
required

Entity type.

Available options:
INDIVIDUAL,
BUSINESS
​
email
string | null
required

Email address.

​
phoneNumber
string | null
required

Phone number.

​
firstName
string | null
required

First name (individuals).

​
lastName
string | null
required

Last name (individuals).

​
businessName
string | null
required

Business name (businesses).

​
country
string | null
required

Country code (ISO 3166-1 alpha-2).

​
addressLine1
string | null
required

Address line 1.

​
addressLine2
string | null
required

Address line 2.

​
city
string | null
required

City.

​
region
string | null
required

Region / state / province.

​
zipCode
string | null
required

ZIP / postal code.

​
crypto
object
required

Crypto-specific details. Present when type is CRYPTO, otherwise null.

​
bank
object
required

Bank-specific details. Present when type is BANK, otherwise null.

​
nxosnet
object
required

Internal NXOS→NXOS details. Present when type is NXOSNET, otherwise null.

​
createdAt
string
required

When the beneficiary was created.