# Transactions

Every TherosAI payment is inscribed on Solana as an immutable transaction. This API surfaces the indexed transaction record — queryable by vault, date range, status, and type.

***

## Get a transaction

`GET /v1/transactions/{tx_id}`

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

**Response `200 OK`**

```json
{
  "tx_id": "tx_4f7c1a",
  "wallet_id": "wal_9f3a2b",
  "type": "payment",
  "recipient": "api.perplexity.ai",
  "amount": "2.50",
  "currency": "USDC",
  "status": "confirmed",
  "tx_signature": "5KtP...xyz",
  "on_chain_slot": 321847293,
  "policy_id": "pol_conservative",
  "policy_triggered": false,
  "memo": "Query batch #8821",
  "agent_attestation_hash": "sha256:a3f2b1...",
  "solscan_url": "https://solscan.io/tx/5KtP...xyz",
  "solana_fm_url": "https://solana.fm/tx/5KtP...xyz",
  "timestamp": "2026-04-29T12:00:00Z"
}
```

***

## List transactions for a wallet

`GET /v1/wallets/{wallet_id}/transactions`

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

**Query parameters**

| Parameter | Type    | Description                                                                                    |
| --------- | ------- | ---------------------------------------------------------------------------------------------- |
| `status`  | string  | `confirmed`, `pending`, `blocked`, `failed`                                                    |
| `from`    | string  | ISO 8601 start timestamp                                                                       |
| `to`      | string  | ISO 8601 end timestamp                                                                         |
| `type`    | string  | `payment`, `funding`, `withdrawal`, `a2a_send`, `a2a_receive`, `escrow_lock`, `escrow_release` |
| `limit`   | integer | Default `20`, max `100`                                                                        |
| `cursor`  | string  | Pagination cursor                                                                              |

***

## List transactions across the organisation

`GET /v1/transactions`

Returns all transactions across all vaults in the organisation.

```bash
curl "https://api.therosai.com/v1/transactions?status=confirmed&limit=100" \
  -H "Authorization: Bearer $THEROS_API_KEY"
```

Supports the same query parameters as the per-vault endpoint, plus:

| Parameter   | Type   | Description                           |
| ----------- | ------ | ------------------------------------- |
| `walletId`  | string | Filter to a specific vault            |
| `recipient` | string | Filter by recipient address or domain |

***

## Transaction types

| Type             | Description                                       |
| ---------------- | ------------------------------------------------- |
| `payment`        | Standard USDC payment from a vault to a recipient |
| `funding`        | USDC allocated from organisation reserve to vault |
| `withdrawal`     | USDC returned from vault to organisation reserve  |
| `a2a_send`       | A2A escrow initiated by this vault                |
| `a2a_receive`    | A2A escrow released to this vault                 |
| `escrow_lock`    | Funds locked in an A2A escrow PDA                 |
| `escrow_release` | Funds released from escrow                        |
| `escrow_refund`  | Funds returned from escrow to sender              |

***

## Transaction statuses

| Status      | Description                                                |
| ----------- | ---------------------------------------------------------- |
| `pending`   | Transaction submitted to Solana, awaiting confirmation     |
| `confirmed` | Confirmed on-chain (single-slot finality)                  |
| `blocked`   | Rejected by spending policy — not submitted to Solana      |
| `failed`    | Submitted to Solana but failed (e.g. insufficient balance) |

***

## Export transactions

`POST /v1/transactions/export`

Generates a CSV or JSON export of transaction history.

```bash
curl -X POST https://api.therosai.com/v1/transactions/export \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "walletId": "wal_9f3a2b",
    "from": "2026-04-01T00:00:00Z",
    "to": "2026-04-30T23:59:59Z"
  }'
```

**Response `200 OK`**

```json
{
  "export_id": "exp_abc123",
  "status": "processing",
  "download_url": null,
  "estimated_ready_at": "2026-04-29T12:01:00Z"
}
```

Poll `GET /v1/transactions/exports/{export_id}` for the download URL, or subscribe to the `export.ready` webhook event.


---

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