Get beneficiary
Retrieve a beneficiary by its identifier. The beneficiary type is resolved automatically.
curl --request GET \
--url https://api.nxos.io/v1/beneficiaries/{beneficiaryId} \
--header 'Authorization: <authorization>'import requests
url = "https://api.nxos.io/v1/beneficiaries/{beneficiaryId}"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.nxos.io/v1/beneficiaries/{beneficiaryId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nxos.io/v1/beneficiaries/{beneficiaryId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.nxos.io/v1/beneficiaries/{beneficiaryId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.nxos.io/v1/beneficiaries/{beneficiaryId}")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nxos.io/v1/beneficiaries/{beneficiaryId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"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"
}{
"error": {
"code": "invalid_request",
"message": "The request body is malformed or missing required fields.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "missing_api_key",
"message": "No Authorization header provided.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "not_found",
"message": "The requested resource was not found.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded: 1000 requests per minute. Retry in 23 seconds.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected server error occurred.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}Headers
Bearer token. Format: Bearer <api_key>
Path Parameters
Query Parameters
Account this beneficiary belongs to.
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, NXOSNET 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).
Address line 1.
Address line 2.
City.
Region / state / province.
ZIP / postal code.
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
Internal NXOS→NXOS details. Present when type is NXOSNET, otherwise null.
Show child attributes
Show child attributes
When the beneficiary was created.
curl --request GET \
--url https://api.nxos.io/v1/beneficiaries/{beneficiaryId} \
--header 'Authorization: <authorization>'import requests
url = "https://api.nxos.io/v1/beneficiaries/{beneficiaryId}"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.nxos.io/v1/beneficiaries/{beneficiaryId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nxos.io/v1/beneficiaries/{beneficiaryId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.nxos.io/v1/beneficiaries/{beneficiaryId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.nxos.io/v1/beneficiaries/{beneficiaryId}")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nxos.io/v1/beneficiaries/{beneficiaryId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"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"
}{
"error": {
"code": "invalid_request",
"message": "The request body is malformed or missing required fields.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "missing_api_key",
"message": "No Authorization header provided.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "not_found",
"message": "The requested resource was not found.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded: 1000 requests per minute. Retry in 23 seconds.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected server error occurred.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}