# Payments

Payments are USDC transfers from an agent vault to a recipient. Every payment is validated against the vault's spending policy before being submitted to Solana — policy violations are rejected on-chain before any state changes.

***

## Send a payment

`POST /v1/payments`

**Request body**

| Field            | Type   | Required | Description                                                              |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------ |
| `walletId`       | string | Yes      | The sending vault ID.                                                    |
| `to`             | string | Yes      | Recipient Solana address or domain string.                               |
| `amount`         | string | Yes      | USDC amount as a decimal string (e.g. `"2.50"`).                         |
| `currency`       | string | Yes      | Must be `"USDC"`.                                                        |
| `memo`           | string | No       | Human-readable description. Stored off-chain, linked to the on-chain tx. |
| `idempotencyKey` | string | No       | A unique key to prevent duplicate payments on retry.                     |

```bash
curl -X POST https://api.therosai.com/v1/payments \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": "wal_9f3a2b",
    "to": "api.perplexity.ai",
    "amount": "2.50",
    "currency": "USDC",
    "memo": "Query batch #8821",
    "idempotencyKey": "batch_8821_pay"
  }'
```

**Response `200 OK`**

```json
{
  "tx_id": "tx_4f7c1a",
  "wallet_id": "wal_9f3a2b",
  "recipient": "api.perplexity.ai",
  "amount": "2.50",
  "currency": "USDC",
  "status": "confirmed",
  "tx_signature": "5KtP...xyz",
  "on_chain_slot": 321847293,
  "policy_triggered": false,
  "memo": "Query batch #8821",
  "timestamp": "2026-04-29T12:00:00Z"
}
```

**Response `402 Payment Required`** — policy violation:

```json
{
  "error": {
    "code": "policy_violation",
    "message": "Transaction blocked by spending policy.",
    "violation": {
      "rule": "max_per_tx",
      "limit": "5.00",
      "attempted": "12.00"
    },
    "wallet_id": "wal_9f3a2b",
    "policy_id": "pol_conservative"
  }
}
```

***

## Get a payment

`GET /v1/payments/{tx_id}`

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

Returns the full transaction object.

***

## Agent-to-agent escrow: create

`POST /v1/payments/a2a`

Initiates an A2A payment with on-chain escrow.

**Request body**

| Field             | Type    | Required | Description                                                     |
| ----------------- | ------- | -------- | --------------------------------------------------------------- |
| `fromWallet`      | string  | Yes      | Requesting agent's vault ID.                                    |
| `toWallet`        | string  | Yes      | Receiving agent's Solana address or TherosAI vault ID.          |
| `amount`          | string  | Yes      | USDC amount.                                                    |
| `currency`        | string  | Yes      | Must be `"USDC"`.                                               |
| `taskDescription` | string  | Yes      | Description of the task. Written on-chain as a memo hash.       |
| `timeoutSeconds`  | integer | No       | Seconds until escrow auto-refunds if unclaimed. Default `3600`. |

```bash
curl -X POST https://api.therosai.com/v1/payments/a2a \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromWallet": "wal_requester",
    "toWallet": "7xKp...nR4Q",
    "amount": "10.00",
    "currency": "USDC",
    "taskDescription": "Summarise Q1 2026 earnings calls — healthcare sector",
    "timeoutSeconds": 3600
  }'
```

**Response `200 OK`**

```json
{
  "escrow_id": "escrow_xyz",
  "from_wallet": "wal_requester",
  "to_wallet": "7xKp...nR4Q",
  "amount": "10.00",
  "status": "locked",
  "solana_address": "9mNq...pR2K",
  "expires_at": "2026-04-29T13:00:00Z",
  "created_at": "2026-04-29T12:00:00Z"
}
```

***

## Agent-to-agent escrow: complete

`POST /v1/payments/a2a/{escrow_id}/complete`

Submits a completion proof. On verification, the escrow is released to the receiving agent.

**Request body**

| Field       | Type   | Required | Description                                                                                                        |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `proofType` | string | Yes      | `"output_hash"`, `"signed_attestation"`, or `"webhook_callback"`                                                   |
| `proof`     | string | Yes      | The proof payload. For `output_hash`: `"sha256:<hex>"`. For `signed_attestation`: a base64-encoded signed payload. |
| `outputUrl` | string | No       | Optional URL to the task output for reference.                                                                     |

```bash
curl -X POST https://api.therosai.com/v1/payments/a2a/escrow_xyz/complete \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "proofType": "output_hash",
    "proof": "sha256:a3f2b1c4...",
    "outputUrl": "https://your-storage.com/result_8821.json"
  }'
```

***

## Agent-to-agent escrow: dispute

`POST /v1/payments/a2a/{escrow_id}/dispute`

Raises a dispute on an active escrow. Either party can raise a dispute before the timeout expires.

```bash
curl -X POST https://api.therosai.com/v1/payments/a2a/escrow_xyz/dispute \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Output does not match task specification",
    "evidence": "sha256:evidence_payload_hash..."
  }'
```

***

## Agent-to-agent escrow: get

`GET /v1/payments/a2a/{escrow_id}`

Returns the current state of an escrow.

***

## Agent-to-agent escrow: list

`GET /v1/payments/a2a`

**Query parameters**

| Parameter  | Type    | Description                                               |
| ---------- | ------- | --------------------------------------------------------- |
| `walletId` | string  | Filter by vault (as sender or recipient).                 |
| `status`   | string  | `locked`, `completed`, `released`, `refunded`, `disputed` |
| `limit`    | integer | Default `20`, max `100`.                                  |
| `cursor`   | string  | Pagination cursor.                                        |


---

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