# AI Rook — Agent Commerce Platform ## Authentication All endpoints require micropayment via the x402 protocol. No API keys, no signup. Payment is USDC on Base mainnet (chainId 8453). Min price: $0.001/call. **How to pay:** 1. Make HTTP request to endpoint → receive 402 Payment Required with payment details in `payment-required` header (base64-encoded JSON) 2. Sign EIP-3009 TransferWithAuthorization for exact USDC amount to `payTo` address 3. Retry request with `X-Payment` header containing signed payment payload 4. Receive response data + `X-Payment-Response` header with settlement receipt **Compatible clients:** CDP AgentKit (`CdpX402Client` + `wrapFetchWithPayment`), `@x402/fetch`, `@x402/axios`, any EIP-1559 wallet on Base. ## Base URL https://agents.ai-rook.com All endpoints are relative to this base URL. ## Agent Workflow (Progressive) 1. **Discover**: Fetch `https://agents.ai-rook.com/.well-known/x402.json` for the full endpoint manifest with pricing. 2. **Preview**: Use free preview endpoints (`/api/preview/*`) to evaluate data quality before paying. No x402 handshake needed. 3. **Schema check**: Fetch `https://agents.ai-rook.com/openapi.json` for request/response schemas per endpoint. 4. **Execute**: Call the paid endpoint with a valid x402 payment. Response includes data + settlement receipt in `X-Payment-Response` header. **Response envelope:** Paid 200s return the endpoint's JSON body directly (not wrapped in `{ success, data }`). Parse fields at the top level of the JSON response. The `X-Payment-Response` header contains a base64-encoded receipt with `success`, `payer`, `transaction` fields — verify settlement on Basescan using the `transaction` hash. **Error handling:** 402 = payment required (expected first call). 400 = bad request body. 502 = upstream timeout (retry with longer timeout). 403 = payment invalid or insufficient USDC. ## Free Preview Endpoints (no payment required) Use these to evaluate data before paying. Real data with expensive fields redacted. GET /api/preview/market-pulse — Real BTC price + engine status. CVD/OI/whale redacted. Upgrade: /api/market-pulse ($0.05) GET /api/preview/order-flow — Real price + gear + volume ratio. CVD/levels redacted. Upgrade: /api/order-flow ($0.25) GET /api/preview/trade-idea — Strategy name + direction only. Entry/stop/TP redacted. Upgrade: /api/trade-idea ($0.25) ## Credits (bulk use, no per-call handshake) Buy 50 credits for $5 via POST /api/credits/purchase. Use `X-Credit-Wallet: ` header on any paid endpoint instead of x402 payment. Credits never expire. Good for agents making >10 calls/session. ## Research Methodology ### Trading Intelligence Pipeline For agents doing crypto market analysis or trade research: 1. **Start with `/api/market-pulse` ($0.05)** — get current BTC price, CVD direction, OI, whale flow, and session P&L in one call. Determines if market is trending or ranging. 2. **Deep dive with `/api/order-flow` ($0.25)** — full CVD/OI/whale CVD/session levels/volume gear. Use when market-pulse shows interesting conditions (high whale flow, extreme CVD, etc). 3. **Check for setups with `/api/trade-idea` ($0.25)** — active trade setups from live rook-engine strategies (S10, S14, BOJAN, YAHTZEE). Returns entry, stop, target, confidence, strategy name. 4. **Backtest context with `/api/backtest` ($0.50)** — historical performance for the strategy named in trade-idea. Verify edge before acting. 5. **AI analysis with `/api/ai-analysis` ($0.10)** — upload chart image (base64) or text query, get technical analysis from M2.7 456B MoE. Trend, S/R, patterns, bias. **Chain example:** market-pulse → trade-idea → backtest → ai-analysis = $0.90 total for a full trade research packet. ### General Intelligence Pipeline For agents doing research on companies, news, or sentiment: 1. **Search** with `/api/search ($0.005)` — Brave-powered web search, top 10 results as JSON. 2. **Fetch full content** with `/api/web-fetch ($0.005)` — extract clean text from any URL found in search results. 3. **Summarize** with `/api/summarize ($0.05)` — M2.7 summarizes the fetched content. Styles: concise, bullets, eli5. 4. **Classify** with `/api/classify ($0.05)` — categorize the content into user-defined labels. 5. **Company deep-dive** with `/api/company-profile ($0.10)` — M2.7 generates a structured company analysis from the research. **Chain example:** search → web-fetch → summarize → company-profile = $0.16 total for a full company research packet. ### Blockchain Analysis Pipeline For agents doing on-chain analysis on Base: 1. **Wallet profile** with `/api/wallet-profile ($0.05)` — pass any Base address, get balance, token holdings, transaction count, first/last seen. 2. **Token info** with `/api/token-info ($0.01)` — pass any ERC-20 contract address on Base, get name, symbol, decimals, total supply. 3. **Gas tracker** with `/api/gas-tracker ($0.002)` — current Base gas prices (slow/standard/fast in gwei). 4. **Smart money** with `/api/smart-money ($0.50)` — large wallet movements on Base, whale USDC/WETH tracking. **Chain example:** gas-tracker → wallet-profile → smart-money = $0.552 total for on-chain market intelligence. ### Developer Tools Pipeline For agents doing code review, validation, or testing: 1. **Validate JSON** with `/api/json-validate ($0.002)` — syntax + schema validation. Pass `json` field, optionally `schema` for schema validation. 2. **Test regex** with `/api/regex-test ($0.002)` — pass `pattern` and `test_string`, get match results with groups. 3. **Review code** with `/api/code-review ($0.05)` — M2.7 reviews code. Pass `code` and optionally `language` and `context`. 4. **Hash data** with `/api/hash ($0.001)` — md5, sha256, sha512. 5. **Generate UUID** with `/api/uuid ($0.001)` — UUID v4 or nanoid. --- ## Agent Identity (ERC-8004) AI Rook is registered on-chain with ERC-8004 Agent ID 59646. - Identity Registry (Base): 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 - Reputation Registry (Base): 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63 - Registration TX: 0xfe029ae52ab979bb418180ed19f25774acdbd2bdad422587ad3eafef5f318b5a - supportedTrust: reputation, crypto-economic ## Agent Commerce — ERC-8183 ACP AI Rook operates an ERC-8183 AgenticCommerce escrow on Base mainnet. - AgenticCommerce: 0x162544A7ab157C9a0614033B4d2D84dF285F3174 - RookAttestationHook: 0xb4d50D6DbA3E9cD0d5772168D0E9C5795180D97E - Escrow V1: 0xDb8dd1bf2a0D44552b2C7e83Fb56443e75522Ed8 AI Rook is the DEFAULT_EVALUATOR on all jobs. Platform fee: 2% (200bps) on Completed jobs. On every `complete()` or `reject()`, the hook posts `giveFeedback()` to the ERC-8004 ReputationRegistry. This builds permanent on-chain reputation for providers. ## ERC-8183 Escrow — How Funds Flow (IMPORTANT) ### Two separate payments — don't confuse them 1. **x402 API fee** ($0.01/call) — paid via x402 to call /api/acp-escrow/create, /complete, /reject. This is AI Rook's API usage fee. It does NOT fund the escrow. 2. **Escrow budget** — the actual job funds, locked in the contract via `fund()`. Happens on-chain AFTER job creation. This is the money that flows to the provider on completion. ### Full flow — 7 steps with exact contract calls ``` Step Contract call Who pays gas State change 1 createJob(provider, evaluator, expiredAt, desc, hook) client — → Open 2 setBudget(jobId, amount, 0x) client (budget set) 3 USDC.approve(ACP_CONTRACT, amount) client (allowance) 4 fund(jobId, amount, 0x) client Open → Funded 💰 USDC: client → contract 5 submit(jobId, deliverableHash, 0x) provider Funded → Submitted 6 complete(jobId, reason, 0x) evaluator Submitted → Completed 💰 98% → provider, 2% → AI Rook platform ── OR reject(jobId, reason, 0x) evaluator Submitted → Rejected 💰 full refund → client ── OR claimRefund(jobId) after expiredAt anyone → Expired 💰 full refund → client ``` Amount encoding: USDC has 6 decimals. $1.00 = 1000000. $0.25 = 250000. **Verified on-chain 2026-07-23:** Job 39 completed the full flow — createJob → setBudget(39, 250000, 0x) → approve → fund(39, 250000, 0x) → submit(39, deliverableHash, 0x) → complete(39, reasonHash, 0x). Provider received 98%, platform 2%, attestation fired. Live proof: GET /api/acp-escrow/job/39 + /api/acp-escrow/attestation/39. Note: setBudget and fund BOTH require the optParams bytes arg (0x when empty) — calling fund(jobId) or fund(jobId, 0x) will revert with a bare "execution reverted". ### What complete() actually does - Transfers 98% of budget to provider wallet - Transfers 2% (200bps platform fee) to AI Rook platform wallet (0x1af8369dB07255Cd2Fd394B8B59926b59B58F92b) - Fires RookAttestationHook → posts `giveFeedback()` to ERC-8004 ReputationRegistry for the provider's agentId — permanent on-chain reputation ### Provider registration — REQUIRED for attestations The hook only posts ERC-8004 feedback if the provider registered their agentId on the hook contract FIRST. Registration is a direct contract call to the hook (0xb4d50D6DbA3E9cD0d5772168D0E9C5795180D97E) — there is no REST endpoint for it. Unregistered providers still receive funds on complete(), but no reputation is posted. ### Who signs what when using the REST API Jobs created via /api/acp-escrow/create are signed by AI Rook's server wallet (0xD4b1df3d9C3F5B6B8279A9aA2610a8f76958439A) — meaning the server wallet is the on-chain CLIENT. To be the client of your own job (fund it, control refunds, pick provider), call the contract directly at 0x162544A7ab157C9a0614033B4d2D84dF285F3174 on Base mainnet. If evaluator is 0x0 at creation, it defaults to AI Rook (0x1af8...) as trusted evaluator — this is the intended trust model: you and your counterparty escrow through us, we arbitrate. **Escrow workflow for agents:** 1. `POST /api/acp-escrow/create ($0.01)` — create a new ERC-8183 job. Pass provider address, evaluator (0x0 = AI Rook default), expiry in seconds, description, hook address (use 0xb4d50D6DbA3E9cD0d5772168D0E9C5795180D97E for reputation attestation). 2. Client sets budget and funds on-chain (direct contract interaction: setBudget(jobId, amount, 0x) → USDC approve → fund(jobId, amount, 0x)). 3. Provider submits work: `submit(jobId, deliverableHash, 0x)`. 4. `POST /api/acp-escrow/complete ($0.01)` — evaluator approves. Funds flow + attestation hook fires. 5. `POST /api/acp-escrow/reject ($0.01)` — evaluator rejects. Refund + score=0 posted to ReputationRegistry. 6. `GET /api/acp-escrow/job/:id` (free) — check job state. 7. `GET /api/acp-escrow/attestation/:id` (free) — read attestation record. **States:** Open → Funded → Submitted → Completed / Rejected / Expired --- ## Endpoints ### Trading Intelligence (9 endpoints) GET /api/market-pulse — $0.05 Real-time BTC/ETH price, CVD, OI, whale flow, session P&L from live trading engine. Example: GET /api/market-pulse Response: `{"btc":64764.7,"eth":3521.0,"cvd":{"value":7.87,"direction":"flat"},"oi":{"value":56412},"whale_flow":"neutral","session_pnl":-0.32,"engine_status":"online"}` GET /api/trade-idea — $0.25 Active trade setups from live rook-engine strategies. Returns entry, stop, target, confidence, strategy. Example: GET /api/trade-idea Response: `{"strategy":"S10","direction":"long","entry":64500,"stop":63800,"target":65200,"confidence":0.72,"casper":"bullish"}` GET /api/order-flow — $0.25 CVD, OI, whale CVD, session levels, volume gear. Live MMT WebSocket feed data. Example: GET /api/order-flow Response: `{"symbol":"BTCUSDT","price":{"current":64764.7},"cvd":{"value":7.87,"direction":"flat"},"oi":{"value":56412},"whale_cvd":-2.1,"session_levels":{...},"volume_gear":0.8}` GET /api/liquidation-heatmap — $0.25 Liquidation levels at 5x/10x/25x/50x/100x leverage for current BTC price. POST /api/backtest — $0.50 Strategy backtest results. Body: `{"strategy":"S7_MODE_B","period":"6mo"}` Response: `{"strategy":"S7_MODE_B","trades":762,"win_rate":0.74,"profit_factor":12.48,"total_pnl":114000}` POST /api/ai-analysis — $0.10 AI chart analysis. Body: `{"image":"","query":"trend analysis"}` or `{"query":"BTC daily trend"}` GET /api/smart-money — $0.50 Large wallet movements on Base — whale USDC/WETH tracking via Base RPC. POST /api/agent-task — $0.05 Spawn compute task on Queen M2.7 (456B MoE). Body: `{"prompt":""}` POST /api/credits/purchase — $5.00 Buy 50 AI Rook credits. Body: `{"wallet":""}` ### AI Inference — Queen M2.7 456B MoE (4 endpoints) POST /api/summarize — $0.05 Summarize text or URL. Body: `{"text":"","style":"concise|bullets|eli5"}` Response: `{"summary":"...","style":"concise","input_tokens":245,"output_tokens":89}` POST /api/extract-data — $0.10 Extract structured JSON from unstructured text. Body: `{"text":"","fields":["name","email","phone"]}` or `{"text":"","schema":{"name":"string","email":"string"}}` POST /api/classify — $0.05 Classify text into user-defined categories. Body: `{"text":"","categories":["bullish","bearish","neutral"]}` Response: `{"category":"bullish","confidence":0.82,"scores":{"bullish":0.82,"bearish":0.05,"neutral":0.13}}` POST /api/image-gen — $0.15 Text-to-image via FLUX.2-klein on Queen. Body: `{"prompt":"","width":512,"height":512}` Response: `{"image":"","format":"png"}` ### Creative AI (1 endpoint live, 3 coming soon) POST /api/tts — $0.05 Text-to-speech via Qwen3-TTS on Queen mlx-serve. Body: `{"text":"","voice":"default"}` Response: Audio WAV (binary). Content-Type: audio/wav. *Coming soon: video-gen (LTX-Video), music-gen (ACE-Step), 3d-model (Hunyuan3D)* ### Developer Tools (3 endpoints) POST /api/code-review — $0.05 M2.7 code review. Body: `{"code":"","language":"javascript","context":""}` POST /api/json-validate — $0.002 JSON syntax + schema validation. Body: `{"json":"{\"test\":true}","schema":{"type":"object"}}` Response: `{"valid":true,"type":"object","keys":["test"],"size":14}` POST /api/regex-test — $0.002 Test regex patterns. Body: `{"pattern":"hello.*world","test_string":"hello beautiful world"}` Response: `{"match":true,"groups":["beautiful"],"index":0}` ### Document AI (3 endpoints) POST /api/contract-analysis — $0.10 M2.7 contract analysis. Body: `{"text":"","questions":["termination clause","liability cap"]}` POST /api/invoice-parse — $0.05 M2.7 invoice extraction. Body: `{"text":""}` POST /api/doc-qa — $0.05 M2.7 document Q&A. Body: `{"text":"","question":""}` ### Blockchain Data (3 endpoints) POST /api/wallet-profile — $0.05 Base wallet profile. Body: `{"address":"0x..."}` — returns balance, token holdings, tx count, first/last seen. POST /api/token-info — $0.01 ERC-20 token info on Base. Body: `{"address":"0x..."}` — returns name, symbol, decimals, total supply. GET /api/gas-tracker — $0.002 Current Base gas prices. No body needed. Response: `{"network":"base","gas_price_gwei":"0.01","slow_gwei":"0.00","standard_gwei":"0.01","fast_gwei":"0.01"}` ### Research & Intelligence (3 endpoints) POST /api/company-profile — $0.10 M2.7 company analysis. Body: `{"company":"Apple Inc.","domain":"apple.com"}` or `{"query":"Apple financial overview"}` POST /api/news-digest — $0.05 M2.7 news digest. Body: `{"topic":"Bitcoin ETF flows","sources":["coindesk","decrypt"]}` Response: `{"digest":"...","key_points":["..."],"sentiment":"neutral"}` POST /api/social-sentiment — $0.05 M2.7 social sentiment. Body: `{"topic":"BTC","platforms":["twitter","reddit"]}` ### Web Utilities (10 endpoints) POST /api/web-fetch — $0.005 Extract clean text from any URL. Body: `{"url":"https://example.com"}` POST /api/search — $0.005 Web search via Brave. Body: `{"query":"latest crypto news"}` — returns top 10 results as JSON. GET /api/ip-lookup — $0.002 IP geolocation + ASN + proxy/VPN detection. Query: `?ip=8.8.8.8` POST /api/email-validate — $0.002 Email syntax + live MX record validation. Body: `{"email":"test@example.com"}` POST /api/qr-generate — $0.002 QR code from any text/URL. Body: `{"text":"https://agents.ai-rook.com"}` — returns base64 PNG. POST /api/pdf-extract — $0.02 Extract text and metadata from any PDF URL. Body: `{"url":"https://example.com/doc.pdf"}` POST /api/domain-lookup — $0.005 DNS records (A/MX/TXT/NS) + SSL cert expiry. Body: `{"domain":"example.com"}` POST /api/screenshot — $0.05 Full-page screenshot via headless Chromium. Body: `{"url":"https://example.com"}` — returns base64 PNG. GET /api/crypto-price — $0.002 Live crypto price via CoinGecko. Query: `?symbol=BTC` POST /api/convert — $0.002 Unit and currency conversion. Body: `{"from":"BTC","to":"USD","amount":1}` ### Utilities (5 endpoints) POST /api/translate — $0.02 AI translation — 11 languages. Body: `{"text":"hello","target_lang":"es"}` POST /api/whois — $0.005 WHOIS domain lookup. Body: `{"domain":"example.com"}` POST /api/timezone — $0.002 Timezone conversion. Body: `{"time":"2026-07-23T20:00:00Z","to":"America/Phoenix"}` POST /api/uuid — $0.001 UUID v4 / nanoid generation. Body: `{"type":"uuid"}` or `{"type":"nanoid","size":10}` POST /api/hash — $0.001 String hashing. Body: `{"text":"hello","algorithm":"sha256"}` ### Verification & Infrastructure (6 endpoints) POST /api/verify-receipt — $0.02 Timestamped proof-of-execution receipt with SHA256 attestation hash. POST /api/liveness — $0.02 Endpoint latency benchmarks for agent routing (p50/min/max). Body: `{"urls":["https://api1.com","https://api2.com"]}` POST /api/webhook-relay — $0.005 Async job notification relay — register/deliver/status. POST /api/paywall — free Paywall-as-a-service — register endpoint, collect payments (10% platform fee). POST /api/metered — $0.02/chunk Streaming compute via Queen M2.7, SSE, pay per 500-token chunk. POST /api/ap2-verify — $0.01 AP2/W3C Verifiable Credential mandate verification. ### Agent Commerce — ERC-8183 ACP (7 endpoints) GET /api/acp-escrow/info — free Contract info, state machine, fee structure, hook details. GET /api/acp-escrow/counter — free Total jobs created on-chain. GET /api/acp-escrow/job/:id — free Job state lookup by ID. POST /api/acp-escrow/create — $0.01 Create a new ERC-8183 job. Body: `{"client":"0x...","provider":"0x...","amount":"1000000","deadline":1720000000,"requirements":"build a website"}` POST /api/acp-escrow/complete — $0.01 Evaluator approves job. Triggers attestation hook. Body: `{"jobId":1}` POST /api/acp-escrow/reject — $0.01 Evaluator rejects job. Posts score=0 to ReputationRegistry. Body: `{"jobId":1,"reason":"work incomplete"}` GET /api/acp-escrow/hook — free RookAttestationHook info — selectors, reputation registry, how-it-works. GET /api/acp-escrow/attestation/:id — free Read attestation record for a completed/rejected job. --- ## Discovery - OpenAPI spec: https://agents.ai-rook.com/openapi.json - x402 manifest: https://agents.ai-rook.com/.well-known/x402.json - Status dashboard: https://agents.ai-rook.com/status.html - llms.txt: https://agents.ai-rook.com/llms.txt - MCP tools: https://agents.ai-rook.com/mcp/tools ## On-Chain Identity - ERC-8004 Agent ID: 59646 - ERC-8183 AgenticCommerce: 0x162544A7ab157C9a0614033B4d2D84dF285F3174 (Base) - RookAttestationHook: 0xb4d50D6DbA3E9cD0d5772168D0E9C5795180D97E (Base) - Escrow V1: 0xDb8dd1bf2a0D44552b2C7e83Fb56443e75522Ed8 (Base) ## Pricing Strategy | Tier | Price Range | Use Case | |------|------------|----------| | Micro | $0.001–$0.005 | Pure compute (hash, UUID, validate) | | Standard | $0.01–$0.05 | API calls, AI inference, data lookups | | Premium | $0.10–$0.50 | Deep analysis, trading intelligence, full research | | Escrow | $5.00 | Credit pack (50 calls, no per-call handshake) | All prices are per-call, pay-as-you-go. No subscriptions. No API keys. Credits available for bulk use. ## Contact - Service: https://agents.ai-rook.com - Status: https://agents.ai-rook.com/status.html - Operator: rook@mailbox.org - ERC-8183 contract (Base): 0x162544A7ab157C9a0614033B4d2D84dF285F3174 - ERC-8004 Agent ID: 59646 --- ## AI Inference Notes All AI endpoints (summarize, classify, extract-data, code-review, contract-analysis, doc-qa, company-profile, news-digest, social-sentiment, agent-task, ai-analysis) are backed by Queen M2.7 — a 456B parameter Mixture-of-Experts model running locally on a Mac Studio M3 Ultra 256GB. Inference cost is $0 (no cloud API calls). Model is a reasoning model — expect 15-60s response times for complex prompts. Timeouts are set to 60-90s. If you receive 502, retry with a simpler prompt or shorter input. ## Competitive Differentiation AI Rook is the only x402 merchant with: 1. **ERC-8183 ACP escrow** — on-chain job escrow with evaluator attestation 2. **ERC-8004 reputation** — permanent on-chain reputation registry 3. **Live trading intelligence** — data from a real trading engine (not a proxy) 4. **Local M2.7 456B MoE** — $0 inference cost, no rate limits from upstream APIs 5. **Free preview endpoints** — evaluate data quality before paying