REST FIRST / RELEASE 0.1

Make one useful request.

The API uses wallet ownership challenges, immutable quotes, explicit budgets and x402 v2. Mainnet is unavailable. Use local mock payments for engineering tests or configure Base Sepolia with a real facilitator.

1. Authenticate without sending funds

POST /v1/auth/challenge
{"wallet":"0xYOUR_PUBLIC_ADDRESS"}

Sign the returned message with personal_sign.
POST /v1/auth/verify
{"challenge_id":"…","signature":"0x…"}

Use the returned access_token in Authorization: Bearer.
The session lasts 15 minutes. EOA wallets only in this release.

Free preview without a wallet

POST /v1/documents/preview
Content-Type: application/pdf
Body: PDF binary (up to 1 MiB, 3 pages)

Returns at most 500 characters and a service recommendation. No OCR, saved upload, quote or payment. Three attempts per connection and 30 globally per minute; respect Retry-After on 429. Full processing still requires wallet authentication.

Download the zero-dependency Node.js preview client. Run node preview.mjs for the synthetic sample or node preview.mjs ./sample.pdf for your chosen PDF.

2. Inspect and quote a document

POST /v1/uploads                        → upload ticket
PUT /v1/uploads/{upload_id}             → PDF binary
Authorization: Bearer {upload_token}
Content-Type: application/pdf

POST /v1/documents/preflight
{"upload_id":"…","sku":"document.text"}

The upload token is a single-use capability expiring in ten minutes. Do not put it in a URL. The PDF expires in 24 hours. Malformed, encrypted and oversized documents are rejected before a paid quote.

3. Negotiate payment once

POST /v1/documents/jobs
Authorization: Bearer {session}
{"quote_id":"…","max_price_minor":"40000"}

402 + PAYMENT-REQUIRED → x402 buyer signs → retry same quote
PAYMENT-SIGNATURE: {base64 x402 v2 payload}

202 → GET /v1/jobs/{order_id}             → free status/result
GET /v1/receipts/{receipt_id}             → free receipt

The server validates network, USDC asset, recipient and amount, verifies through the official SDK and reserves the authorization before settlement. An ambiguous settlement stays pending for manual reconciliation; repeating a request cannot trigger a second settlement.

AgentVault

POST /v1/vault/checkpoints
{"sku":"vault.checkpoint","snapshot":{"state":"…"}}
→ quote → POST /v1/orders/{quote_id} → vault_id

GET /v1/vault/{vault_id}                 → own/granted data
GET /v1/vault/{vault_id}/export          → free portable JSON
DELETE /v1/vault/{vault_id}              → free deletion

POST /v1/vault/{vault_id}/grants
{"target_wallet":"0x…","hours":72}     → paid handoff quote
DELETE /v1/vault/{vault_id}/grants/{grant_id}

Paying does not grant ownership of another wallet's data. A handoff may only be created by an authenticated owner, and the recipient must authenticate too. The MVP uses AES-256-GCM at rest with a server-managed key. A client-encrypted snapshot can be stored as opaque JSON, but lost client keys cannot be recovered.

Human Oracle closed beta

Submit one factual public question and one or two HTTPS sources to POST /v1/oracle/quotes. A human accepts scope and a deadline before a quote exists. At most five open requests. The service is disabled until an operator is assigned. This is not 24/7 support or high-stakes professional advice.

Prices and limits

Operation	USDC	Limit
document.text	0.04	20 pages / 10 MB
document.tables	0.18	20 pages / worker required
document.ocr	0.12	10 pages / worker required
vault.checkpoint	0.04	32 KB / 7 days
vault.capsule	0.10	256 KB / 30 days
vault.handoff	0.16	72 hours maximum
oracle.quick_check	3.00	Human acceptance required
oracle.source_compare	5.00	Human acceptance required

Verifiable examples

Compare a synthetic PDF with its extracted JSON and run the integration check without payment.

Unavailable features

Smart-contract wallet signatures (EIP-1271), interoperable MCP, Bazaar listings, mainnet payments, automatic refunds and single-payment bundles are not enabled. Their release gates are documented in the delivery package.

Download OpenAPI ↗ · Trust and privacy ↗

Authenticated integration with a spending limit

The reference client authenticates wallet ownership, uploads with a separate single-use token, validates the quote and x402 challenge, and limits this authorized test to 0.04 test USDC on Base Sepolia. Keep the original order reference to recover its result and receipt without another purchase.

Download the official SDK integration example

import {ExternalBuyer} from './external-buyer.js';
const client = new ExternalBuyer({origin: location.origin, provider: window.ethereum});
await client.inspect(pdfFile); // ownership signature, upload, quote; no payment
await client.buy();            // explicit wallet authorization; maximum 40000
await client.recover();        // same order and receipt; no payment

This restricted reference is pinned to the authorized pilot wallets; it is not a general-purpose checkout. Never store wallet signatures or session tokens in logs or persistent browser storage.