List wallets
curl --request GET \
--url https://api.natural.com/wallets \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.natural.com/wallets"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.natural.com/wallets', 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.natural.com/wallets",
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: Bearer <token>"
],
]);
$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.natural.com/wallets"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
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.natural.com/wallets")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.natural.com/wallets")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"type": "wallet",
"id": "wal_019cd1798d714ce765e0486a417c23dc",
"attributes": {
"status": "active",
"walletType": "standard",
"isDefault": true,
"createdAt": "2026-01-04T15:30:00.000Z",
"displayName": "Operating",
"description": null,
"tags": {
"environment": "production"
},
"balance": {
"available": 120000,
"total": 125000,
"currency": "USD"
},
"claims": {
"amount": 5000,
"count": 1
},
"depositInstructions": {
"bankName": "Natural",
"accountNumber": null,
"routingNumber": null
}
},
"relationships": {
"party": {
"data": {
"type": "party",
"id": "pty_019cd1798d617f65a79cb965dda9eac3"
}
}
}
},
{
"type": "wallet",
"id": "wal_019cd1798d72cf01303c7c04148c9b8d",
"attributes": {
"status": "active",
"walletType": "vault",
"isDefault": false,
"createdAt": "2026-01-04T15:30:00.000Z",
"displayName": "Vault",
"description": null,
"tags": {},
"balance": {
"available": 500000,
"total": 500000,
"currency": "USD"
},
"claims": {
"amount": 0,
"count": 0
},
"depositInstructions": {
"bankName": "Natural",
"accountNumber": null,
"routingNumber": null
}
},
"relationships": {
"party": {
"data": {
"type": "party",
"id": "pty_019cd1798d617f65a79cb965dda9eac3"
}
}
}
}
],
"meta": {
"pagination": {
"hasMore": false,
"nextCursor": null
}
}
}{
"errors": [
{
"code": "invalid_value",
"detail": "The information you entered isn't valid. Please check it and try again.",
"status": "400",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "unauthenticated",
"detail": "Authentication is required.",
"status": "401",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "forbidden",
"detail": "You do not have permission to perform this action.",
"status": "403",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "not_found",
"detail": "The requested resource was not found.",
"status": "404",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "conflict",
"detail": "The request conflicts with the current resource state.",
"status": "409",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "invalid_value",
"detail": "Too big: expected string to have <=80 characters",
"status": "422",
"source": {
"pointer": "/data/attributes/description"
},
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "mfa_required",
"detail": "MFA verification required",
"status": "428",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "rate_limited",
"detail": "Too many requests. Please try again later.",
"status": "429",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "server_error",
"detail": "Something went wrong.",
"status": "500",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "not_implemented",
"detail": "This operation is not available.",
"status": "501",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "bad_gateway",
"detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.",
"status": "502",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "service_unavailable",
"detail": "The service is temporarily unavailable.",
"status": "503",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}Wallets
List wallets
List party wallets or the wallets granted to the acting agent
GET
/
wallets
List wallets
curl --request GET \
--url https://api.natural.com/wallets \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.natural.com/wallets"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.natural.com/wallets', 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.natural.com/wallets",
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: Bearer <token>"
],
]);
$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.natural.com/wallets"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
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.natural.com/wallets")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.natural.com/wallets")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"type": "wallet",
"id": "wal_019cd1798d714ce765e0486a417c23dc",
"attributes": {
"status": "active",
"walletType": "standard",
"isDefault": true,
"createdAt": "2026-01-04T15:30:00.000Z",
"displayName": "Operating",
"description": null,
"tags": {
"environment": "production"
},
"balance": {
"available": 120000,
"total": 125000,
"currency": "USD"
},
"claims": {
"amount": 5000,
"count": 1
},
"depositInstructions": {
"bankName": "Natural",
"accountNumber": null,
"routingNumber": null
}
},
"relationships": {
"party": {
"data": {
"type": "party",
"id": "pty_019cd1798d617f65a79cb965dda9eac3"
}
}
}
},
{
"type": "wallet",
"id": "wal_019cd1798d72cf01303c7c04148c9b8d",
"attributes": {
"status": "active",
"walletType": "vault",
"isDefault": false,
"createdAt": "2026-01-04T15:30:00.000Z",
"displayName": "Vault",
"description": null,
"tags": {},
"balance": {
"available": 500000,
"total": 500000,
"currency": "USD"
},
"claims": {
"amount": 0,
"count": 0
},
"depositInstructions": {
"bankName": "Natural",
"accountNumber": null,
"routingNumber": null
}
},
"relationships": {
"party": {
"data": {
"type": "party",
"id": "pty_019cd1798d617f65a79cb965dda9eac3"
}
}
}
}
],
"meta": {
"pagination": {
"hasMore": false,
"nextCursor": null
}
}
}{
"errors": [
{
"code": "invalid_value",
"detail": "The information you entered isn't valid. Please check it and try again.",
"status": "400",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "unauthenticated",
"detail": "Authentication is required.",
"status": "401",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "forbidden",
"detail": "You do not have permission to perform this action.",
"status": "403",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "not_found",
"detail": "The requested resource was not found.",
"status": "404",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "conflict",
"detail": "The request conflicts with the current resource state.",
"status": "409",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "invalid_value",
"detail": "Too big: expected string to have <=80 characters",
"status": "422",
"source": {
"pointer": "/data/attributes/description"
},
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "mfa_required",
"detail": "MFA verification required",
"status": "428",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "rate_limited",
"detail": "Too many requests. Please try again later.",
"status": "429",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "server_error",
"detail": "Something went wrong.",
"status": "500",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "not_implemented",
"detail": "This operation is not available.",
"status": "501",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "bad_gateway",
"detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.",
"status": "502",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "service_unavailable",
"detail": "The service is temporarily unavailable.",
"status": "503",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}Authorizations
Bearer authentication: send your API key, agent key, or OAuth access token as Authorization: Bearer <credential>.
Headers
Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money.
Maximum string length:
1024Query Parameters
Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf.
Pattern:
^pty_[0-9a-f]{32}$Maximum results per page.
Required range:
1 <= x <= 100Cursor from the previous page.
Maximum string length:
1024Response
Successful Response
Wallet resources visible to this credential. Agents receive the same wallet fields, limited to wallets granted to their current agent or customer connection, with an additional agentDefault flag.
Was this page helpful?