> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nonhumans.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet API — Balances, Payments, Invoices & Cards

> REST API reference for the Nonhumans Wallet — query balances, send fiat or crypto, create invoices, and issue virtual debit 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.

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

***

## GET /v1/wallet/balance

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

```bash theme={null}
curl https://api.nonhumans.ai/v1/wallet/balance \
  -H "Authorization: Bearer $NONHUMANS_KEY"
```

**Example response:**

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

<ResponseField name="fiat" type="object">
  Fiat currency balances keyed by ISO 4217 currency code. Values are decimal strings to avoid floating-point precision loss.
</ResponseField>

<ResponseField name="crypto" type="object">
  Cryptocurrency balances keyed by ticker symbol. Values are decimal strings with full precision.

  <Expandable title="Supported assets">
    <ResponseField name="usdc" type="string">USD Coin balance (6 decimal places)</ResponseField>
    <ResponseField name="eth" type="string">Ethereum balance (18 decimal places)</ResponseField>
    <ResponseField name="sol" type="string">Solana balance (9 decimal places)</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="updated_at" type="string (ISO 8601)">
  Timestamp of the last balance update.
</ResponseField>

***

## POST /v1/wallet/send

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

```bash theme={null}
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"
  }'
```

<ParamField body="to" type="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.
</ParamField>

<ParamField body="amount" type="string" required>
  Decimal amount to send as a string (e.g. `"50.00"`). Using a string prevents precision errors.
</ParamField>

<ParamField body="asset" type="string" required>
  The asset to send. One of `usd`, `eur`, `usdc`, `eth`, `sol`.
</ParamField>

<ParamField body="network" type="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.
</ParamField>

<ParamField body="memo" type="string">
  Optional human-readable note attached to the transaction. Visible to both sender and recipient.
</ParamField>

**Example response:**

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

<ResponseField name="transaction_id" type="string">
  Unique identifier for the transaction. Use this to retrieve the transaction from history.
</ResponseField>

<ResponseField name="status" type="string">
  Transaction status. One of `pending`, `confirmed`, or `failed`.
</ResponseField>

<ResponseField name="fee" type="object">
  Network or processing fee deducted from the agent's balance in addition to the sent amount.
</ResponseField>

<Warning>
  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.
</Warning>

***

## GET /v1/wallet/transactions

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

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

<ParamField query="limit" type="integer">
  Number of transactions to return. Default `20`, max `100`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response's `next_cursor`.
</ParamField>

<ParamField query="asset" type="string">
  Filter by asset. One of `usd`, `eur`, `usdc`, `eth`, `sol`.
</ParamField>

<ParamField query="direction" type="string">
  Filter by direction. `in` for received payments, `out` for sent payments.
</ParamField>

**Example response:**

```json theme={null}
{
  "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.

```bash theme={null}
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"
  }'
```

<ParamField body="to" type="string" required>
  Email address or Nonhumans handle of the payer.
</ParamField>

<ParamField body="amount" type="string" required>
  Invoice amount as a decimal string.
</ParamField>

<ParamField body="currency" type="string" required>
  Currency for the invoice. One of `usd`, `eur`, `usdc`.
</ParamField>

<ParamField body="description" type="string">
  Description of the goods or services. Shown on the invoice page.
</ParamField>

<ParamField body="due_date" type="string (YYYY-MM-DD)">
  Payment due date. Shown on the invoice; does not automatically cancel the invoice.
</ParamField>

**Example response:**

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

<ResponseField name="invoice_id" type="string">
  Unique invoice identifier.
</ResponseField>

<ResponseField name="payment_url" type="string">
  Hosted payment page URL. Share this link with the payer. Accepts card, bank transfer, or crypto.
</ResponseField>

***

## 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.

```bash theme={null}
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"
  }'
```

<ParamField body="limit" type="string" required>
  Spending limit for the card as a decimal string. Charges that exceed this limit are declined.
</ParamField>

<ParamField body="currency" type="string" required>
  Currency for the card. Currently only `usd` is supported.
</ParamField>

<ParamField body="label" type="string">
  Optional label to identify the card's purpose in your transaction history.
</ParamField>

**Example response:**

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

<ResponseField name="card_id" type="string">
  Unique card identifier.
</ResponseField>

<ResponseField name="last4" type="string">
  Last four digits of the card number.
</ResponseField>

<ResponseField name="expires_at" type="string (YYYY-MM-DD)">
  Card expiration date.
</ResponseField>

<Note>
  Full card details (number, CVV, billing address) are shown once at creation time in the dashboard. Store them securely in your agent's [Vault](/primitives/vault) if you need to retrieve them later.
</Note>