# Relaystation — full agent reference Pay-per-call API platform for AI agents and developers. Prepaid; no monthly fees, no subscription. Network: Base Sepolia. Payment assets: USDC, EURC (same EIP-3009 settlement; 1:1 micros pricing). ## Baton — the model A baton is a prepaid storage object configured along five independent groups. Pick the values that fit your use, pay once at create, draw down the prepaid quotas until expiry. There are no post-create per-use charges. 1. Write behavior — one of four: - Single object — stores one file, image, video, or binary payload. Replace it any time; delete it when done. - Append — a text log you add entries to over time. - Append, hash-chained — an append log where each entry is hash-linked to the previous, so tampering is detectable. Auto-includes a document-witness. - Overwrite — a text file you replace in full; only the latest is kept. 2. Capacity — size (storage), duration (validity), egress (the read budget). A single write over 3 MB uploads via a presigned URL the create returns. 3. Sharing — collaborator tokens. Up to 100 per baton; each token carries a scope (read / write / read_write), an optional read cap, and an optional expiry. 4. Lifecycle — burn-after-reading (delete the baton once every token read cap is consumed) and disposal (soft delete with a grace period, or hard delete). 5. Trust — document-witness. When enabled, Relaystation cryptographically signs the content hash and keeps the signed record for 7 years; verify offline against Relaystation's published key. Funding paths (all resolve to one customerId): - x402 lodestone (no account) — sign EIP-3009 off-chain, one HTTPS call carries payload + X-Payment header. Wallet IS the identity. - x402 wallet — same x402 settlement, wallet has signed in and carries history. - Stripe-funded balance — human signs up via OAuth, tops up via Stripe Checkout, balance debited per order. ## Preconfigs — fast-start prefills Five preconfigs set the five-group values to common shapes; every value remains configurable on create. They are fast-start prefills, not the organizing principle. - Drop — Store a file. Single object; multi-read until expiry. - Pass — Share a file. Single object plus a read-capped token; burns once the token is consumed. - Scratchpad — Collaborate. Append log; tokens for collaborators. - Checkpoint — Save state. Overwrite; replace the snapshot as you go. - Ledger — Audited Ledger. Append, hash-chained; tamper-evident; auto-witnessed. ## Pricing One engine-computed quote is the published price. Quote any shape with POST /v1/baton/quote; create it with POST /v1/baton. The price is the engine quote of the shape, frozen at create. No catalog prices; no tiers as priced SKUs. Universal network-minimum floor: $0.001 (covers L2 gas under optimistic billing). Every billable order is charged max(engine_quote, network_minimum). ## x402 wire summary Header: X-Payment: . Assets: USDC or EURC. The 402 challenge lists one accepts[] entry per asset; pick one and sign its EIP-712 domain. Domain: { name, version, chainId, verifyingContract } — take name + version from the chosen accepts[].extra (USDC = "USD Coin"/"2" on Base mainnet, "USDC"/"2" on Base Sepolia; EURC = "EURC"/"2"), verifyingContract = that asset's contract. Types: TransferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce). Server response success: HTTP 200/201 + PAYMENT-RESPONSE header (base64 receipt with tx hash, payer, amount). Server response payment-required: HTTP 402 with body { x402Version: 2, accepted: [...], error: "PAYMENT_REQUIRED" }. ## Trust model Two prepaid flags: - hashChaining — chained per-entry hash, append-only enforced (a chained baton with overwrite=true returns 409). - witness — flat document-witness ($0.05 standalone, OR prepaid at create when chained — requires: witness). A chained baton (hashChaining=true) auto-commits a prepaid witness. The customer can call POST /trust/document-witness any time; if they never do, the auto-seal-at-expiry sweeper pass fires it at expiry, free, while content is live. Verify offline via GET /trust/proof + POST /trust/challenge. Public, free, per-IP rate-limited on challenge. ## Full endpoint roster ### System / discovery GET /v1/baton/system/info — agent-facing descriptor. GET /v1/baton/system/egress-ips — outbound webhook delivery IPs (currently dynamic; HMAC-verify advisory in body). GET /v1/baton/prices — the named preconfigs + their default shapes (fast-start prefills). POST /v1/baton/quote — public price-of-record for any shape (a preconfig ref or a custom shape). GET /openapi.json — OpenAPI 3.1. GET /llms.txt — concise summary. GET /llms-full.txt — this document. GET /.well-known/mcp.json — MCP advertisement. POST /mcp — MCP transport (JSON-RPC over HTTP). ### Baton lifecycle POST /v1/baton — create. Billable. Pays at create; the whole baton config (resources + flags) is frozen onto the baton. GET /v1/baton/{id} — read (owner-addressed). GET /v1/baton/{tokenId} — read (token-addressed; "tok_<43-char>" replaces {id} on the URL). No Authorization header required. POST /v1/baton/{id} — write (owner-addressed; append for append / append-chained batons, overwrite/replace for single-object / overwrite batons). POST /v1/baton/{tokenId} — write (token-addressed). GET /v1/baton/{id}/entries — paginated entries (owner). GET /v1/baton/{tokenId}/entries — paginated entries (token). GET /v1/baton/{id}/tail — long-poll for new entries (owner). GET /v1/baton/{tokenId}/tail — long-poll (token). DELETE /v1/baton/{id} — soft-delete + scheduled purge per on_expiration. POST /v1/baton/{id}/add — buy another tier of the same preset. Billable. POST /v1/baton/{id}/extend — buy à-la-carte dimensions (size, duration, egress, writes). Billable. GET /v1/baton/{id}/meta — read metadata + flags snapshot. POST /v1/baton/{id}/meta — mutate metadata (allowlisted fields only). GET /v1/baton/{id}/event-logs — paginated audit log. ### Tokens (collaborators) POST /v1/baton/{id}/tokens — mint a token (read / write / read_write capability + per-token caps). GET /v1/baton/{id}/tokens — list tokens. POST /v1/baton/{id}/tokens/{tokenId} — modify (mutable subset) OR revoke ({"revoke":true}). ### Trust POST /v1/baton/{id}/trust/document-witness — freeze + sign the baton (billable $0.05 standalone OR free on prepaid path). POST /v1/baton/{id}/trust/verify-chain — verify chained-hash integrity (free). POST /v1/baton/{id}/trust/challenge — public, free; per-IP rate-limited. Match a candidate against a witnessed baton. GET /v1/baton/{id}/trust/proof — public, free; retrieve the signed attestation. ### Auth bootstrap GET /v1/auth/challenge?wallet=0x... — wallet sign-in nonce. POST /v1/auth/verify — verify EIP-191 sig, mint wallet JWT. ### Account GET /v1/account — customer profile + balance. POST /v1/account/api-keys/regenerate — rotate API key (dashboard auth only). GET /v1/account/products / POST /v1/account/products/{product}/enable — enrollment primitive (no valid product slugs registered). ### Webhooks POST /v1/webhooks — register a webhook (returns secret ONCE). GET /v1/webhooks — list. GET /v1/webhooks/{id} — detail. PUT /v1/webhooks/{id} — update. DELETE /v1/webhooks/{id} — delete. GET /v1/webhooks/{id}/deliveries — paginated delivery history. ### Billing POST /v1/billing/checkout — Stripe Checkout for balance top-up (dashboard auth). GET /v1/billing/packs — public pack list + custom-amount bounds. ## MCP tools POST /mcp dispatches the JSON-RPC catalog: - baton.prices — wraps GET /v1/baton/prices. Returns the named preconfigs + their default shapes. - baton.quote — wraps POST /v1/baton/quote. Returns the published price for any baton shape (a preconfig ref or a custom shape). - webhook.register — chassis primitive; register a webhook. tools/list and tools/call per MCP "Streamable HTTP" transport. Auth headers thread through to the wrapped REST routes unchanged. ## Auth modes - x402 EIP-3009 USDC payment in X-Payment header (lodestone — no account). - API key in Authorization: Bearer rs_live_... (signup at app.relaystation.ai). - Wallet JWT (challenge + verify at /v1/auth/challenge + /v1/auth/verify). - rs_session cookie (dashboard only; cookie-only routes scoped to /v1/account/api-keys/* + /v1/billing/checkout). ## Idempotency Every billable POST/PUT/DELETE accepts and requires Idempotency-Key: on the request. Replays within 24h return the cached response (chassis tunable). ## Errors Spec-shaped JSON body: { error: "", code: "" }. Status set: 400, 401, 402, 403, 404, 409, 410, 422, 429, 500, 503. ## Docs https://relaystation.ai/api-reference