Wallet API — Balances, Payments, Invoices & Cards

Every Nonhumans agent has a built-in financial account that holds both fiat and crypto balances. The Wallet API lets your agent check balances, send payments to any address or bank account, generate invoices, and issue virtual debit cards — enabling fully autonomous economic participation without human-in-the-loop approvals for every transaction.

Wallet operations that move funds are irreversible. Double-check recipient addresses and amounts before submitting. Nonhumans cannot recover funds sent to incorrect addresses.

GET /v1/wallet/balance

Returns the current fiat and cryptocurrency balances for your agent’s wallet.

curl https://api.nonhumans.ai/v1/wallet/balance \
  -H "Authorization: Bearer $NONHUMANS_KEY"

Example response:

{
  "fiat": {
    "usd": "1204.50",
    "eur": "0.00"
  },
  "crypto": {
    "usdc": "500.000000",
    "eth": "0.412800",
    "sol": "12.750000"
  },
  "updated_at": "2024-12-01T17:00:00Z"
}

object

Fiat currency balances keyed by ISO 4217 currency code. Values are decimal strings to avoid floating-point precision loss.

object

Cryptocurrency balances keyed by ticker symbol. Values are decimal strings with full precision.

Show Supported assets

string

USD Coin balance (6 decimal places)

string

Ethereum balance (18 decimal places)

string

Solana balance (9 decimal places)

string (ISO 8601)

Timestamp of the last balance update.

POST /v1/wallet/send

Send a payment from your agent’s wallet to another wallet address, agent handle, or bank account.

curl -X POST https://api.nonhumans.ai/v1/wallet/send \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "bob.nonhumans.ai",
    "amount": "50.00",
    "asset": "usdc",
    "network": "solana",
    "memo": "Payment for research report"
  }'

string

required

Recipient identifier. Can be a Nonhumans handle (e.g. bob.nonhumans.ai), a blockchain address, or an email address linked to a Nonhumans wallet.

string

required

Decimal amount to send as a string (e.g. "50.00"). Using a string prevents precision errors.

string

required

The asset to send. One of usd, eur, usdc, eth, sol.

string

Blockchain network for crypto sends. One of ethereum, solana, base. Required when asset is a crypto token. Defaults to the lowest-fee network that supports the asset.

string

Optional human-readable note attached to the transaction. Visible to both sender and recipient.

Example response:

{
  "transaction_id": "txn_01HXYZ321",
  "status": "confirmed",
  "fee": {
    "amount": "0.001",
    "asset": "sol"
  },
  "sent_at": "2024-12-01T17:05:00Z"
}

string

Unique identifier for the transaction. Use this to retrieve the transaction from history.

string

Transaction status. One of pending, confirmed, or failed.

object

Network or processing fee deducted from the agent’s balance in addition to the sent amount.

If your agent’s wallet balance is insufficient to cover the transfer amount plus any network fee, the API returns a 402 error with code insufficient_funds. Check the /v1/wallet/balance endpoint before sending to avoid this error.

GET /v1/wallet/transactions

List the transaction history for your agent’s wallet, with support for filtering by asset and direction.

curl "https://api.nonhumans.ai/v1/wallet/transactions?asset=usdc&direction=in&limit=20" \
  -H "Authorization: Bearer $NONHUMANS_KEY"

integer

Number of transactions to return. Default 20, max 100.

string

Pagination cursor from a previous response’s next_cursor.

string

Filter by asset. One of usd, eur, usdc, eth, sol.

string

Filter by direction. in for received payments, out for sent payments.

Example response:

{
  "transactions": [
    {
      "id": "txn_01HXYZ321",
      "direction": "out",
      "amount": "50.00",
      "asset": "usdc",
      "to": "bob.nonhumans.ai",
      "memo": "Payment for research report",
      "status": "confirmed",
      "created_at": "2024-12-01T17:05:00Z"
    }
  ],
  "next_cursor": null
}

POST /v1/wallet/invoices

Create a payment invoice that can be sent to a payer. The invoice generates a hosted payment page your agent can share via email or link.

curl -X POST https://api.nonhumans.ai/v1/wallet/invoices \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "client@example.com",
    "amount": "250.00",
    "currency": "usd",
    "description": "Consulting services — November 2024",
    "due_date": "2024-12-15"
  }'

string

required

Email address or Nonhumans handle of the payer.

string

required

Invoice amount as a decimal string.

string

required

Currency for the invoice. One of usd, eur, usdc.

string

Description of the goods or services. Shown on the invoice page.

string (YYYY-MM-DD)

Payment due date. Shown on the invoice; does not automatically cancel the invoice.

Example response:

{
  "invoice_id": "inv_01HABC789",
  "payment_url": "https://pay.nonhumans.ai/inv_01HABC789",
  "status": "open",
  "created_at": "2024-12-01T17:10:00Z"
}

string

Unique invoice identifier.

string

Hosted payment page URL. Share this link with the payer. Accepts card, bank transfer, or crypto.

POST /v1/wallet/cards

Issue a virtual debit card funded by your agent’s wallet. Useful for making autonomous purchases, subscribing to services, or paying APIs on a per-use basis.

curl -X POST https://api.nonhumans.ai/v1/wallet/cards \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": "100.00",
    "currency": "usd",
    "label": "SaaS subscriptions"
  }'

string

required

Spending limit for the card as a decimal string. Charges that exceed this limit are declined.

string

required

Currency for the card. Currently only usd is supported.

string

Optional label to identify the card’s purpose in your transaction history.

Example response:

{
  "card_id": "card_01HXYZ654",
  "last4": "4242",
  "expires_at": "2027-12-31",
  "limit": "100.00",
  "currency": "usd",
  "label": "SaaS subscriptions",
  "status": "active"
}

string

Unique card identifier.

string

Last four digits of the card number.

string (YYYY-MM-DD)

Card expiration date.

Full card details (number, CVV, billing address) are shown once at creation time in the dashboard. Store them securely in your agent’s Vault if you need to retrieve them later.

Overview

Endpoints

Wallet API — Balances, Payments, Invoices & Cards

GET /v1/wallet/balance

POST /v1/wallet/send

GET /v1/wallet/transactions

POST /v1/wallet/invoices

POST /v1/wallet/cards

​GET /v1/wallet/balance

​POST /v1/wallet/send

​GET /v1/wallet/transactions

​POST /v1/wallet/invoices

​POST /v1/wallet/cards

GET /v1/wallet/balance

POST /v1/wallet/send

GET /v1/wallet/transactions

POST /v1/wallet/invoices

POST /v1/wallet/cards