# Wallets

Agent vaults are provisioned, funded, and managed via the Wallets API. Each vault is a non-custodial PDA on Solana, isolated per agent and governed by an attached spending policy.

***

## Create a wallet

`POST /v1/wallets`

Provisions a new agent vault. Settles in under one second.

**Request body**

| Field      | Type      | Required | Description                                                             |
| ---------- | --------- | -------- | ----------------------------------------------------------------------- |
| `agentId`  | string    | Yes      | Your identifier for this agent. Must be unique within the organisation. |
| `label`    | string    | Yes      | Human-readable name for the dashboard.                                  |
| `policyId` | string    | Yes      | ID of the spending policy to attach.                                    |
| `tags`     | string\[] | No       | Optional tags for filtering in the dashboard.                           |

```bash
curl -X POST https://api.therosai.com/v1/wallets \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_research_v2",
    "label": "Research Agent — Market Data",
    "policyId": "pol_conservative",
    "tags": ["research", "production"]
  }'
```

**Response `200 OK`**

```json
{
  "wallet_id": "wal_9f3a2b",
  "solana_address": "7xKp...nR4Q",
  "agent_id": "agent_research_v2",
  "label": "Research Agent — Market Data",
  "usdc_balance": "0.00",
  "policy": {
    "policy_id": "pol_conservative",
    "name": "Conservative — Research Agent",
    "max_per_tx": "5.00",
    "max_per_day": "50.00",
    "max_per_month": "500.00"
  },
  "status": "active",
  "tags": ["research", "production"],
  "created_at": "2026-04-29T12:00:00Z"
}
```

***

## Get a wallet

`GET /v1/wallets/{wallet_id}`

```bash
curl https://api.therosai.com/v1/wallets/wal_9f3a2b \
  -H "Authorization: Bearer $THEROS_API_KEY"
```

**Response `200 OK`**

Returns the wallet object. Same schema as the create response, plus `updated_at` and `last_transaction_at`.

***

## List wallets

`GET /v1/wallets`

**Query parameters**

| Parameter | Type    | Description                                                                  |
| --------- | ------- | ---------------------------------------------------------------------------- |
| `status`  | string  | Filter by status: `active`, `idle`, `policy_violation`, `frozen`, `unfunded` |
| `tags`    | string  | Comma-separated tag filter. Returns wallets matching all specified tags.     |
| `limit`   | integer | Results per page. Default `20`, max `100`.                                   |
| `cursor`  | string  | Pagination cursor from previous response.                                    |

```bash
curl "https://api.therosai.com/v1/wallets?status=active&tags=production&limit=50" \
  -H "Authorization: Bearer $THEROS_API_KEY"
```

**Response `200 OK`**

```json
{
  "data": [ /* array of wallet objects */ ],
  "has_more": true,
  "next_cursor": "cursor_abc123"
}
```

***

## Update a wallet

`PATCH /v1/wallets/{wallet_id}`

Updatable fields: `label`, `policyId`, `tags`, `status` (for freeze/unfreeze).

Policy changes take effect within one Solana slot (\~400ms).

```bash
curl -X PATCH https://api.therosai.com/v1/wallets/wal_9f3a2b \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Research Agent — Market Data v2",
    "policyId": "pol_conservative_strict"
  }'
```

To freeze a wallet:

```json
{ "status": "frozen" }
```

To unfreeze:

```json
{ "status": "active" }
```

***

## Fund a wallet

`POST /v1/wallets/{wallet_id}/fund`

Allocates USDC from the organisation reserve to the vault.

```bash
curl -X POST https://api.therosai.com/v1/wallets/wal_9f3a2b/fund \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "100.00", "currency": "USDC" }'
```

**Response `200 OK`**

```json
{
  "wallet_id": "wal_9f3a2b",
  "funded_amount": "100.00",
  "usdc_balance": "100.00",
  "org_balance_remaining": "4900.00"
}
```

***

## Fund multiple wallets

`POST /v1/wallets/fund-batch`

```bash
curl -X POST https://api.therosai.com/v1/wallets/fund-batch \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allocations": [
      { "walletId": "wal_9f3a2b", "amount": "100.00" },
      { "walletId": "wal_7d1e4c", "amount": "250.00" }
    ]
  }'
```

All allocations succeed or all fail — this is an atomic operation.

***

## Withdraw from a wallet

`POST /v1/wallets/{wallet_id}/withdraw`

Returns USDC to the organisation reserve. Pass `"all"` to withdraw the full balance.

```bash
curl -X POST https://api.therosai.com/v1/wallets/wal_9f3a2b/withdraw \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "50.00" }'
```

***

## Set auto-topup

`PUT /v1/wallets/{wallet_id}/auto-topup`

```bash
curl -X PUT https://api.therosai.com/v1/wallets/wal_9f3a2b/auto-topup \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "triggerBelow": "10.00",
    "topupAmount": "50.00"
  }'
```

***

## Rotate session token

`POST /v1/wallets/{wallet_id}/rotate-token`

Revokes the current session authority token and issues a new one.

```bash
curl -X POST https://api.therosai.com/v1/wallets/wal_9f3a2b/rotate-token \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ttlSeconds": 3600 }'
```

**Response `200 OK`**

```json
{
  "wallet_id": "wal_9f3a2b",
  "session_token": "eyJ...",
  "expires_at": "2026-04-29T13:00:00Z"
}
```

***

## Archive a wallet

`DELETE /v1/wallets/{wallet_id}`

Archives the vault. The vault must have a zero USDC balance before archiving. Transaction history is retained permanently on-chain.

```bash
curl -X DELETE https://api.therosai.com/v1/wallets/wal_9f3a2b \
  -H "Authorization: Bearer $THEROS_API_KEY"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.therosai.com/api-reference/wallets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.