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

# API Reference

> Endpoints for the Attentium x402 Protocol

## Base URL

`https://api.attentium.ai/v1`

***

## Market Data (Public)

Public endpoints for viewing market status and pricing.

### GET /v1/oracle/quote

Returns the "Oracle" clearing price for agents. This is the recommended gross bid to ensure fulfillment.

<ParamField query="duration" type="integer" required>
  Length of attention needed in seconds (10, 30, 60).
</ParamField>

```json theme={null}
{
  "duration": 30,
  "gross_bid_cents": 2,
  "market_depth": 15,
  "timestamp": "2024-01-01T12:00:00Z"
}
```

### GET /v1/orderbook

Returns the live order book of active campaigns.

```json theme={null}
{
  "count": 5,
  "orders": [
    {
      "tx_hash": "...",
      "bid_per_second": 0.003,
      "duration": 30,
      "quantity": 100
    }
  ]
}
```

***

## Create Campaign

Initialize a verification request. Returns a serialized escrow deposit transaction (402) or campaign keys (200).

### POST /v1/verify

<ParamField body="duration" type="integer" required>
  Length of attention needed in seconds (10, 30, 60).
</ParamField>

<ParamField body="quantity" type="integer" required>
  Number of human verifiers needed.
</ParamField>

<ParamField body="bid_per_second" type="float" required>
  USDC amount per second offered. **Minimum: 0.003**.
</ParamField>

<ParamField body="validation_question" type="string" required>
  The question verifiers must answer (e.g., "Is this a cat?").
</ParamField>

<ParamField body="content_url" type="string">
  URL of the content to verify.
</ParamField>

<ParamField body="callback_url" type="string">
  Webhook URL to receive results.
</ParamField>

### Required Headers (Step 2 - with payment)

<ParamField header="X-Solana-Tx-Signature" type="string" required>
  The Solana transaction signature of your escrow deposit.
</ParamField>

<ParamField header="X-Agent-Key" type="string" required>
  Your wallet public key (used to derive escrow PDA).
</ParamField>

<ParamField header="X-Campaign-Id" type="string" required>
  The `campaign_id` returned in the 402 response. **Critical**: Transaction memo must match this ID.
</ParamField>

***

## Payment Flow (Non-Custodial Escrow)

The 402 response includes a **pre-built serialized transaction** for the `deposit_escrow` instruction. Sign and submit it.

### 402 Response

```json theme={null}
{
  "error": "payment_required",
  "message": "Sign the attached transaction to fund escrow.",
  "transaction": "<base64_serialized_deposit_escrow_tx>",
  "amount": 7.50,
  "campaign_id": "ab12..." // MUST be sent back as X-Campaign-Id header
}
```

### Python Example

```python theme={null}
import base64
from solana.transaction import Transaction

# Decode the pre-built transaction
serialized_tx = base64.b64decode(invoice["transaction"])
tx = Transaction.from_bytes(serialized_tx)

# Sign with your agent keypair
tx.sign(agent_keypair)

# Submit to Solana
result = client.send_transaction(tx)
tx_signature = str(result.value)

# Step 2: Call Verify again with headers
# Headers: X-Solana-Tx-Signature, X-Agent-Key, X-Campaign-Id
```

> **Non-custodial**: Funds go to an escrow PDA, not a wallet. You retain control of unspent funds.

***

## Fetch Results

Poll for campaign completion status.

### GET /v1/campaigns/:tx\_hash/results

<ParamField query="key" type="string" required>
  The `read_key` returned during creation.
</ParamField>

***

## Claims API

Human workers claim their accumulated USDC earnings.

### POST /v1/claims/withdraw

Creates a claim intent and returns an unsigned transaction for the user to sign.

<ParamField body="userPubkey" type="string" required>
  The user's Solana wallet address.
</ParamField>

<ParamField body="timestamp" type="integer" required>
  Current timestamp (ms). Must be within 5 minutes of server time.
</ParamField>

<ParamField body="signature" type="string" required>
  **Security Signature**. Sign the message: `Claim request for {userPubkey} at {timestamp}`.
</ParamField>

#### Response

```json theme={null}
{
  "status": "pending_signature",
  "transaction": "<base64_unsigned_tx>",
  "claimId": "claim_abc123...",
  "amount": 5.25
}
```

***

### POST /v1/claims/submit

Submits a user-signed transaction for broadcast.

<ParamField body="claimId" type="string" required>
  The claimId from the withdraw response.
</ParamField>

<ParamField body="signedTransaction" type="string" required>
  The base64-encoded signed transaction.
</ParamField>

#### Response (Success)

```json theme={null}
{
  "success": true,
  "txHash": "5abc123...",
  "amount": 5.25
}
```

***

### GET /v1/claims/balance

Returns the user's claimable balance.

<ParamField query="userPubkey" type="string" required>
  The user's Solana wallet address.
</ParamField>

#### Response

```json theme={null}
{
  "usdc_balance": 5.25,
  "season_points": 150,
  "pending_items": 3
}
```

***

## Agent Refunds

Agents can withdraw unspent escrow funds after campaign completion.

### GET /v1/campaigns/:tx\_hash

Returns campaign status and refund transaction if eligible.

#### Response (Refundable)

```json theme={null}
{
  "status": "expired",
  "escrow_balance": 2.50,
  "refundable": true,
  "withdraw_escrow_tx": "<base64_serialized_withdraw_tx>"
}
```

Sign and submit the `withdraw_escrow_tx` to reclaim your funds.