Skip to main content

​
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.
​
duration
integer
required
Length of attention needed in seconds (10, 30, 60).
{
  "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. 
{
  "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

​
duration
integer
required
Length of attention needed in seconds (10, 30, 60).
​
quantity
integer
required
Number of human verifiers needed.
​
bid_per_second
float
required
USDC amount per second offered. Minimum: 0.003.
​
validation_question
string
required
The question verifiers must answer (e.g., “Is this a cat?”).
​
content_url
string
URL of the content to verify.
​
callback_url
string
Webhook URL to receive results.

​
Required Headers (Step 2 - with payment)

​
X-Solana-Tx-Signature
string
required
The Solana transaction signature of your escrow deposit.
​
X-Agent-Key
string
required
Your wallet public key (used to derive escrow PDA).
​
X-Campaign-Id
string
required
The campaign_id returned in the 402 response. Critical: Transaction memo must match this ID.

​
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

{
  "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

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

​
key
string
required
The read_key returned during creation.

​
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.
​
userPubkey
string
required
The user’s Solana wallet address.
​
timestamp
integer
required
Current timestamp (ms). Must be within 5 minutes of server time.
​
signature
string
required
Security Signature. Sign the message: Claim request for {userPubkey} at {timestamp}.

​
Response

{
  "status": "pending_signature",
  "transaction": "<base64_unsigned_tx>",
  "claimId": "claim_abc123...",
  "amount": 5.25
}

​
POST /v1/claims/submit

Submits a user-signed transaction for broadcast.
​
claimId
string
required
The claimId from the withdraw response.
​
signedTransaction
string
required
The base64-encoded signed transaction.

​
Response (Success)

{
  "success": true,
  "txHash": "5abc123...",
  "amount": 5.25
}

​
GET /v1/claims/balance

Returns the user’s claimable balance.
​
userPubkey
string
required
The user’s Solana wallet address.

​
Response

{
  "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)

{
  "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.