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

# Wallet Details

> Get wallet details, deposit address, and vault-allocation availability

Returns wallet details, a structured `funding` block describing both funding paths (external deposit and vault allocation), and — for backward compatibility — a flat `funding_instructions` string.

```bash theme={null}
curl -s \
  -H "Authorization: Bearer $AXON_DECISION_API_KEY" \
  "https://api.axon402.com/v1/wallets/$WALLET_ID"
```

## Response

```json theme={null}
{
  "wallet_id": "uuid",
  "name": "string",
  "address": "0x...",
  "role": "vault",
  "is_active": true,
  "derived_path": "m/44'/60'/0'/0/1",
  "funding": {
    "external_deposit": {
      "address": "0x...",
      "asset": "USDC",
      "network": "eip155:8453",
      "network_label": "Base",
      "deposit_uri": "ethereum:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913@8453/transfer?address=0x...",
      "instructions": "Send USDC on Base to this address."
    },
    "vault_allocation": {
      "available": true,
      "reason_unavailable": null,
      "vault_wallet_id": "uuid"
    }
  },
  "funding_instructions": "Send USDC on Base (chain 8453) to 0x..."
}
```

## Fields

### Top level

| Field | Type | Description |
| :- | :- | :- |
| `wallet_id` | `string` | UUID of the wallet |
| `name` | `string` | Human-readable wallet name |
| `address` | `string` | On-chain wallet address (Base) |
| `role` | `string` | `"vault"` or `"agent_pocket"` |
| `is_active` | `boolean` | Whether the wallet is currently active |
| `derived_path` | `string` | HD derivation path |
| `funding` | `object` | Structured description of both funding paths — see below |
| `funding_instructions` | `string` | Flat, single-sentence funding hint. **Deprecated** — preserved for backward compatibility only; removed after v0.2.0. New consumers should read `funding.external_deposit.instructions`. |

### `funding.external_deposit`

The **Deposit to Wallet** path. This is the universal funding method: an external on-chain USDC transfer into the wallet's address. It works for every org regardless of signing mode.

| Field | Type | Description |
| :- | :- | :- |
| `address` | `string` | The on-chain address to send USDC to (same as the top-level `address` field) |
| `asset` | `string` | Always `"USDC"` in v1 |
| `network` | `string` | CAIP-2 chain identifier. `"eip155:8453"` for Base mainnet. |
| `network_label` | `string` | Human-readable network name, e.g. `"Base"` |
| `deposit_uri` | `string` | **EIP-681 USDC transfer URI**. Render this as a QR code for wallet apps (Coinbase Wallet, Rainbow, MetaMask, etc.); it encodes the token contract, chain id, and destination address in one payload. |
| `instructions` | `string` | Human-readable one-line instruction, suitable for display in a dashboard or CLI. |

### `funding.vault_allocation`

The **Allocate from Vault** path. This is an internal vault → pocket transfer, and it is only available when the server holds the vault private key (i.e., the org is in `full` / server-signed mode). Browser-signed orgs cannot allocate.

| Field | Type | Description |
| :- | :- | :- |
| `available` | `boolean` | `true` if the caller can invoke `POST /v1/wallets/:id/fund` or `POST /v1/orgs/:id/transfers/fund` against this wallet. `false` otherwise. |
| `reason_unavailable` | `string \| null` | When `available` is `false`, one of the enum values below. `null` when `available` is `true`. |
| `vault_wallet_id` | `string \| null` | The UUID of the vault that would be the source of an allocation. `null` for vault wallets themselves (a vault can't allocate to itself). |

#### `reason_unavailable` values

| Value | Meaning |
| :- | :- |
| `"browser_signed_org"` | The org's signing mode is `browser`; the server has no vault signer. Deposit externally instead. |
| `"wallet_is_vault"` | This wallet is the vault itself — a vault cannot allocate to itself. |
| `"no_vault"` | The organization does not currently have an active vault wallet to allocate from. |
| `null` | Vault allocation IS available for this wallet. |

## Funding modes at a glance

| Path | Available when | How |
| :- | :- | :- |
| **Deposit to Wallet** (external) | Always | Scan the EIP-681 `deposit_uri` with any Base-compatible wallet app and send USDC. |
| **Allocate from Vault** (internal) | `funding.vault_allocation.available === true` | `POST /v1/wallets/:wallet_id/fund` with `amount_usdc` — the daemon signs the vault → pocket transfer with the server-held vault key. |

> [!NOTE]
>
> In v1, every AXON wallet is reachable via the external deposit path. Vault allocation is an optimisation for server-signed orgs: it avoids an on-chain round-trip by moving balance inside the same custody boundary.

## Error handling

* **404 NOT\_FOUND** — `wallet_id` doesn't exist or the caller isn't authorized to see it.
* **`VAULT_ALLOCATION_UNAVAILABLE`** is never returned by this GET — it surfaces from `POST /v1/wallets/:id/fund` and `POST /v1/orgs/:id/transfers/fund` when a caller tries to allocate on a browser-signed org. This GET route tells you ahead of time whether that call would succeed (`funding.vault_allocation.available`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.