{ "openapi": "3.1.0", "info": { "title": "SwarmIO Cloud API", "version": "1.0.0", "description": "The x402-payable and public agent surface of ioswarm.io — this root document is what agent discovery (x402scan register-origin, the agentcash probe) reads. The full contract, including the credit-billed account API (sk_swarm_ key), is at /api/v1/openapi.json; the human/agent doc is /llms.txt.\n\nAI that does real work for you. One POST kicks off a job that searches the web, reads sources, and writes a cited report; poll for the result.\n\nAgent onboarding (no browser, no human): 1) GET /api/v1/auth/config → Supabase url + anon key. 2) POST {supabase_url}/auth/v1/signup → access_token (email confirmation off). 3) POST /api/v1/agent/register → agent id. 4) POST /api/v1/account/api-keys → sk_swarm_ key (shown once). 5) Authorization: Bearer sk_swarm_… on everything else. Starter credits land automatically on the first authenticated call.\n\nThe full agent doc is https://ioswarm.io/llms.txt; the A2A agent card is at /.well-known/agent-card.json; an MCP facade is at /mcp.", "x-guidance": "Agent surface. Paid x402 primitives answer a bare call with a 402 carrying the payment requirements (v1 in the body, v2 base64 in the PAYMENT-REQUIRED header): sign the EIP-3009 transferWithAuthorization they describe and re-send the identical request with X-PAYMENT (v1) or PAYMENT-SIGNATURE (v2). Paid per call: /api/v1/search ($0.02, 25 free/day), /api/v1/search/report ($0.05), /api/v1/news/brief ($0.05), /api/v1/market/price ($0.02, 10 free/day), /api/v1/video/transcript ($0.02, 10 free/day), /api/v1/video/search ($0.02, 25 free/day), /api/v1/x402/quote ($0.01), /api/v1/x402/fetch ($0.02), /api/v1/x402/chat ($0.02), /api/v1/feeds/{feed} ($0.01-$0.02; a free 24h-delayed edition sits at /api/v1/feeds/{feed}/sample). Long-running jobs: POST /api/v1/x402/run/{mode} ($0.25-$1.85 per run; the paying wallet becomes the account). Credit-billed account surface (API key, not x402): GET /api/v1/auth/config to discover the Supabase backend, sign up (email confirmation is off), POST /api/v1/agent/register, then POST /api/v1/account/api-keys for an sk_swarm_ key.", "contact": { "url": "https://ioswarm.io", "email": "support@ioservices.io" } }, "servers": [ { "url": "https://ioswarm.io" } ], "paths": { "/llms.txt": { "get": { "operationId": "llmsTxt", "summary": "The agent onboarding doc (plain text). Public.", "security": [], "responses": { "200": { "description": "The onboarding document.", "content": { "text/plain": {} } } } } }, "/api/v1/pulse": { "get": { "operationId": "getPulse", "summary": "Free live data, no key and no account: prices for BTC-USD, ETH-USD, SOL-USD, AMZN and NVDA with the session's change, today's stories from the platform's newest published news digest (with a link to the full cited report), and the market wire's latest headlines. Prices refresh every minute, news every ten minutes. Fixed symbol list. The same document is the MCP tool market.pulse.", "security": [], "responses": { "200": { "description": "The current pulse.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pulse" } } } } } } }, "/api/v1/auth/config": { "get": { "operationId": "getAuthConfig", "summary": "Discover the auth backend. Public.", "security": [], "responses": { "200": { "description": "Supabase project coordinates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthConfig" } } } } } } }, "/api/v1/billing/crypto": { "get": { "operationId": "getCryptoTerms", "summary": "Machine-payable top-up terms: network, asset, receiving address, rate, minimum. Public.", "security": [], "responses": { "200": { "description": "Top-up terms. `enabled:false` means the operator has not published a receiving address yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CryptoTerms" } } } } } } }, "/api/v1/x402/topup": { "get": { "operationId": "getX402Terms", "summary": "x402 top-up terms: resource URL, scheme, networks, asset, price bounds. Public — read the price before you decide to pay.", "security": [], "parameters": [ { "name": "usd", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Purchase size in dollars. Omit for the advertised default ($5). Floor $1, ceiling $1,000 — larger purchases go through Stripe checkout." } ], "responses": { "200": { "description": "Terms of the paid resource. `enabled:false` means no receiving address is published yet." }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "operationId": "x402Topup", "x-payment-info": { "price": { "mode": "dynamic", "currency": "USD", "min": "1.000000", "max": "1000.000000" }, "protocols": [ { "x402": {} } ] }, "summary": "Buy credits over the x402 protocol. Call with no payment header to receive a 402 carrying the payment requirements, then repeat with the signed authorization.", "description": "The standard x402 exchange, both wire versions. First call: no payment header, and the 402 carries the requirements twice — the v1 document in the JSON body (`accepts[]`), the v2 document base64-encoded in the `PAYMENT-REQUIRED` response header. Sign the EIP-3009 `transferWithAuthorization` they describe (you sign only; you broadcast nothing and pay no gas) and repeat the identical request with the payload base64-encoded into `X-PAYMENT` (v1) or `PAYMENT-SIGNATURE` (v2). A facilitator verifies and broadcasts; this service never holds a signing key. Credits land at the same rate card as Stripe, volume bonus included. Settlement is idempotent per on-chain transaction, and shares its payment claim with /api/v1/billing/crypto-topup so one transfer can never credit twice.", "parameters": [ { "name": "usd", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Purchase size in dollars. Omit for the advertised default ($5). Floor $1, ceiling $1,000 — larger purchases go through Stripe checkout." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v1: base64-encoded PaymentPayload. Omit on the first call." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2: base64-encoded PaymentPayload. Takes precedence over X-PAYMENT." } ], "responses": { "200": { "description": "Settled and credited. The settlement document is echoed in `X-PAYMENT-RESPONSE` (v1) or `PAYMENT-RESPONSE` (v2).", "headers": { "X-PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "v1: base64-encoded SettlementResponse." }, "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "v2: base64-encoded SettlementResponse." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "credited": { "type": "boolean" }, "credits": { "type": "integer", "description": "Tokens granted by this payment." }, "balance": { "type": "integer" }, "usd": { "type": "number" }, "transaction": { "type": "string", "description": "Base transaction hash of the settled transfer." }, "payer": { "type": "string" }, "duplicate": { "type": "boolean", "description": "Present when this settlement was already credited." } }, "required": [ "credited" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Payment required — the normal first half of the exchange, not an error. The v1 requirements are the body; the v2 requirements are in `PAYMENT-REQUIRED`.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "v2: base64-encoded PaymentRequired document." } } }, "502": { "description": "The facilitator could not be reached, or settled without returning a transaction. Safe to retry." }, "503": { "description": "Machine payments not configured." } } } }, "/api/v1/x402/run": { "get": { "operationId": "listX402RunResources", "summary": "Every mode sold per run over x402, with its price in USD. Free. The wallet that pays becomes the account — no signup, no key ahead of time.", "security": [], "responses": { "200": { "description": "The run resources.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "resources": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string" }, "url": { "type": "string" }, "usd": { "type": "number" }, "credits": { "type": "integer" }, "description": { "type": "string" } } } }, "how": { "type": "string" } } } } } } } } }, "/api/v1/x402/run/research": { "post": { "operationId": "payForRunResearch", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1.050000" }, "protocols": [ { "x402": {} } ] }, "summary": "A cited, evidence-graded research report on any question: a swarm of agents searches the live web, reads the sources, cross-checks the claims, and grades its own evidence (sourced / partial / unsupported). $1.05 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/news": { "post": { "operationId": "payForRunNews", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.750000" }, "protocols": [ { "x402": {} } ] }, "summary": "A same-day, cross-outlet news digest on a topic or region, every item dated and attributed, with the primary source separated from corroboration. $0.75 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/finance": { "post": { "operationId": "payForRunFinance", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1.200000" }, "protocols": [ { "x402": {} } ] }, "summary": "A data-grounded market brief: live prices and technicals, fundamentals, recent insider and congressional trades, a per-asset thesis and a comparison table — numbers pulled, not generated. $1.20 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/product": { "post": { "operationId": "payForRunProduct", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.250000" }, "protocols": [ { "x402": {} } ] }, "summary": "A cross-retailer product scan: the same items priced across many stores, structured specs and reviews, ranked by price-to-value, bot walls included. $0.25 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/seo": { "post": { "operationId": "payForRunSeo", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1.400000" }, "protocols": [ { "x402": {} } ] }, "summary": "A severity-ranked SEO audit of a live site with an action plan — every finding verified against the site itself. $1.40 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/trips": { "post": { "operationId": "payForRunTrips", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1.250000" }, "protocols": [ { "x402": {} } ] }, "summary": "A researched itinerary: real inventory, prices, and timing for a destination and dates. $1.25 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/trainer": { "post": { "operationId": "payForRunTrainer", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.700000" }, "protocols": [ { "x402": {} } ] }, "summary": "A personalized, progressive training program from stated goals and constraints. $0.70 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/meals": { "post": { "operationId": "payForRunMeals", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1.100000" }, "protocols": [ { "x402": {} } ] }, "summary": "A week of meals planned around stated goals, with a shopping list. $1.10 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/wellness": { "post": { "operationId": "payForRunWellness", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1.850000" }, "protocols": [ { "x402": {} } ] }, "summary": "A literature-grounded wellness plan around a stated goal. $1.85 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/mentor": { "post": { "operationId": "payForRunMentor", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1.500000" }, "protocols": [ { "x402": {} } ] }, "summary": "A learning plan for a stated skill: sequence, resources, milestones. $1.50 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/money": { "post": { "operationId": "payForRunMoney", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.950000" }, "protocols": [ { "x402": {} } ] }, "summary": "A personal-finance plan around stated goals and numbers. $0.95 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/policy": { "post": { "operationId": "payForRunPolicy", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1.350000" }, "protocols": [ { "x402": {} } ] }, "summary": "A brief on a bill, rule, or policy area: status, positions, what changes and for whom, cited. $1.35 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/supply": { "post": { "operationId": "payForRunSupply", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1.400000" }, "protocols": [ { "x402": {} } ] }, "summary": "A supply-chain brief on a product or component: suppliers, risks, alternatives. $1.40 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/grants": { "post": { "operationId": "payForRunGrants", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1.150000" }, "protocols": [ { "x402": {} } ] }, "summary": "Matching grants and funders for a stated organization and need, with deadlines and requirements. $1.15 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/quote": { "post": { "operationId": "payForRunQuote", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.950000" }, "protocols": [ { "x402": {} } ] }, "summary": "Quotes gathered for a stated service or purchase, compared. $0.95 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/astrology": { "post": { "operationId": "payForRunAstrology", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.500000" }, "protocols": [ { "x402": {} } ] }, "summary": "A natal reading from server-computed chart positions (birth date required in the input as '- Birth date: YYYY-MM-DD'). $0.50 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/run/horoscope": { "post": { "operationId": "payForRunHoroscope", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.500000" }, "protocols": [ { "x402": {} } ] }, "summary": "The sky right now, computed server-side, read for the caller. $0.50 per run over x402: 402, sign, POST again with the payment header. The paying wallet becomes the account.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "type": "string", "description": "The question or brief (≤ 8,000 characters)." }, "options": { "type": "object", "description": "Mode-specific launch options, optional." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "202": { "description": "Paid and started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "poll_url", "report_url" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "poll_url": { "type": "string" }, "report_url": { "type": "string" }, "events_url": { "type": "string" }, "credentials": { "type": "object", "nullable": true, "description": "{authorization, account, agent_id} when this payment created the account. Shown once." }, "paid": { "type": "object" }, "balance_after_credit": { "type": "integer", "nullable": true }, "next": { "type": "string" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected — the body says which." }, "400": { "description": "No input, input too long, or a payment payload with no payer." }, "403": { "description": "Agent registration is closed and no existing key was presented; the payment was not taken." }, "404": { "description": "Not a mode sold per run." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/search": { "get": { "operationId": "searchGet", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "summary": "Keyless web search. 25 free searches a day per caller (≤5 results, quota block echoed); over the quota the 402 carries x402 payment requirements (≈ $0.02, ≤20 results, no daily cap). No account.", "security": [], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" }, "description": "What to search for (alias: q)." }, { "name": "k", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Results to return (default 8; the free leg clamps to 5, the paid leg to 20)." }, { "name": "freshness", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "day", "week", "month", "year" ] } }, { "name": "domains", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated domain allowlist, e.g. reuters.com,apnews.com." } ], "responses": { "200": { "description": "Answered. Free leg: organic results (≤5) plus a quota block. Paid leg: results (≤20) plus a paid block and the settlement header." }, "402": { "description": "Over the free quota — the payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED). A bare GET (no query parameter) always answers this challenge: the discovery document (free quota, body shape, bazaar extension) rides inside the 402 body, which is what directory validators (CDP /validate among them) read." }, "400": { "description": "Missing or oversized query when a payment header is present — refused before the facilitator is asked. Without a payment header the 402 quotes the price instead." } } }, "post": { "operationId": "searchPost", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "summary": "Same two legs as GET with a JSON body. Over the quota (or with a payment header from the start): 402, sign, re-send with X-PAYMENT / PAYMENT-SIGNATURE.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "k": { "type": "integer" }, "freshness": { "type": "string" }, "domains": { "type": "string" } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "Answered — free leg (quota block) or paid leg (paid block + settlement header)." }, "402": { "description": "Over the free quota — the payment requirements." }, "400": { "description": "Missing or oversized query when a payment header is present — refused before the facilitator is asked. Without a payment header the 402 quotes the price instead." } } } }, "/api/v1/search/report": { "get": { "operationId": "describeSearchReport", "summary": "Describe this x402 primitive. A bare GET on a paid resource answers the 402 challenge (never a bare doc page — that fails CDP's /validate preflight); the discovery document rides inside the 402 body. The report is pay-only — there is no free tier to fall through to.", "security": [], "responses": { "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in: endpoint, price, POST body shape, response shape, the x402 how, and the bazaar extension." }, "200": { "description": "Machine payments are not configured — the plain discovery document, nothing to sell." } } }, "post": { "operationId": "searchReport", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.050000" }, "protocols": [ { "x402": {} } ] }, "summary": "One-call research brief: live web search synthesized into a cited bullet report (every finding ends with its source URL). Pay-only (≈ $0.05): 402, sign, POST again with the payment header. No account.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "k": { "type": "integer", "description": "Results to synthesize (default 8, max 10)." }, "freshness": { "type": "string", "enum": [ "all", "day", "week", "month", "year" ] }, "domains": { "type": "string", "description": "Comma-separated domain allowlist." } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{query, report, results (≤10), usage, paid block + settlement header}." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Missing or oversized query when a payment header is present — refused before the facilitator is asked. Without a payment header the 402 quotes the price instead." }, "502": { "description": "Settled but the search backend or model did not answer — the transaction hash is quoted for support." } } } }, "/api/v1/news/brief": { "get": { "operationId": "describeNewsBrief", "summary": "Describe this x402 primitive. A bare GET on a paid resource answers the 402 challenge (never a bare doc page — that fails CDP's /validate preflight); the discovery document rides inside the 402 body.", "security": [], "responses": { "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in: endpoint, price, empty body (the brief needs no input), response shape, the x402 how, and the bazaar extension." }, "200": { "description": "Machine payments are not configured — the plain discovery document, nothing to sell." } } }, "post": { "operationId": "newsBrief", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.050000" }, "protocols": [ { "x402": {} } ] }, "summary": "Today's market-news brief in one call: the platform's newest published news digest synthesized with the live market wire into a cited bullet brief (every finding ends with its source URL). Pay-only (≈ $0.05): 402, sign, POST again with the payment header. No account; no input required.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Optional and empty — the brief needs no input. A garbage body with a payment header is a 400; without one the 402 quotes the price." } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{as_of, brief, digest, headlines, usage, paid block + settlement header}." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Garbage body with a payment header present — refused before the facilitator is asked. Without a payment header the 402 quotes the price instead." }, "503": { "description": "No fresh news material in the window (digest lands on the operator's schedule) — no payment was taken." }, "502": { "description": "Settled but the model did not answer — the transaction hash is quoted for support." } } } }, "/api/v1/market/price": { "get": { "operationId": "marketPriceGet", "summary": "Keyless two-leg price panel. 10 free lookups a day per caller (quota block echoed); over the quota the 402 carries x402 payment requirements (≈ $0.02). No account.", "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "description": "ticker, optionally EXCHANGE:TICKER — e.g. AAPL, NASDAQ:AAPL, BTCUSD, EURUSD, ES1!" }, { "name": "interval", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1m", "3m", "5m", "15m", "30m", "45m", "1h", "2h", "3h", "4h", "1d", "1day", "1w", "1week", "1mo", "1month" ] }, "description": "candle interval for the panel (default 1d)" }, { "name": "exchange", "in": "query", "required": false, "schema": { "type": "string" }, "description": "pin the TradingView exchange instead of trying candidates" }, { "name": "indicators", "in": "query", "required": false, "schema": { "type": "string" }, "description": "optional comma-list to restrict the panel, e.g. \"sma_20,rsi_14,trend\"" }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "The panel: symbol, exchange, interval, price, change_pct_1/5/20, range, the indicators object, plus a quota block (free leg) or the paid block + settlement header (paid leg)." }, "402": { "description": "Over the free quota — the payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." } } }, "post": { "operationId": "marketPrice", "summary": "Live TradingView price + technical indicators (SMA/EMA, RSI, MACD, ATR, Bollinger, VWMA, trend) for one asset, paid per call over x402. 10 free lookups a day per caller; over the quota ≈ $0.02 per call. An asset TradingView cannot resolve is ALWAYS free — the miss is answered before payment is ever requested ({\"known\": false}), never charged, and never burns quota. No account.", "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "symbol" ], "properties": { "symbol": { "type": "string", "description": "ticker, optionally EXCHANGE:TICKER — e.g. AAPL, NASDAQ:AAPL, BTCUSD, EURUSD, ES1!" }, "interval": { "type": "string", "enum": [ "1m", "3m", "5m", "15m", "30m", "45m", "1h", "2h", "3h", "4h", "1d", "1day", "1w", "1week", "1mo", "1month" ], "description": "candle interval for the panel (default 1d)" }, "exchange": { "type": "string", "description": "pin the TradingView exchange instead of trying candidates" }, "indicators": { "type": "string", "description": "optional comma-list to restrict the panel, e.g. \"sma_20,rsi_14,trend\"" } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "The panel: symbol, exchange, interval, price, change_pct_1/5/20, range, the indicators object, plus a quota block (free leg) or the paid block + settlement header (paid leg)." }, "402": { "description": "Over the free quota (the quote) — the payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED); or a payment the facilitator rejected." }, "400": { "description": "Invalid symbol charset or unknown interval with a payment header present — refused before the facilitator is asked. Without a payment header the 402 quotes the price instead." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/video/transcript": { "post": { "operationId": "videoTranscript", "summary": "YouTube captions for one video as timestamped segments (title, duration, per-moment text) — the media the swarm's own research runs read. 10 free transcripts a day per caller; over the quota ≈ $0.02 per call. A video with no usable caption track (private, deleted, captions disabled, wrong language) is ALWAYS free — the miss is answered before payment is ever requested ({\"known\": false}), never charged, and never burns quota. No account.", "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "One of url or video_id is required.", "properties": { "url": { "type": "string", "description": "a YouTube URL — watch, shorts, youtu.be, live, embed" }, "video_id": { "type": "string", "description": "an 11-character YouTube video id (alternative to url)" }, "lang": { "type": "string", "description": "caption language (default \"en\")" }, "format": { "type": "string", "enum": [ "segments", "text" ], "description": "segments (default, timestamped) or one flat text" } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{known, video_id, url, title, duration_sec, lang, segment_count, segments, text, truncated?, error?, timeout?, quota | paid}." }, "402": { "description": "Over the free quota — the payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Neither url nor video_id (or a garbage body with a payment header) — refused before the facilitator is asked." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/video/search": { "post": { "operationId": "videoSearch", "summary": "YouTube video search — title, channel, duration, view count, live status, with recency filters (within hour/today/week/month/year). 25 free searches a day per caller; over the quota ≈ $0.02 per call. A query with no matching videos is ALWAYS free — an empty result is answered before payment is ever requested ({\"known\": false}), never charged, and never burns quota. Pairs with video-transcript: search here, read there. No account.", "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "what to search for" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "results (default 10)" }, "sort": { "type": "string", "enum": [ "relevance", "rating", "date", "views" ] }, "within": { "type": "string", "enum": [ "hour", "today", "week", "month", "year" ], "description": "recency filter (server-side; the only way to get genuinely recent results)" }, "duration": { "type": "string", "enum": [ "short", "medium", "long" ] } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{known, query, count, results: [{id, title, url, channel, duration_sec, view_count, live_status}], error?, timeout?, quota | paid}." }, "402": { "description": "Over the free quota — the payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Missing query (or a garbage body with a payment header) — refused before the facilitator is asked." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/feeds": { "get": { "operationId": "listFeeds", "summary": "Free catalogue of the pre-staged data feeds: id, description, price, refresh cadence, sections, sources, newest edition and a free sample URL for each. Feeds: news (consolidated news by topic), movers (market movers with reasons), filings (SEC filings digest), calendar (economic + earnings), prediction-markets (Polymarket + Kalshi), ai (AI changelog), security (KEV, CVEs, advisories), trending (attention), regulation (Federal Register + agency actions), crypto-listings (exchange listings + governance). No language model is involved in building any of them.", "security": [], "responses": { "200": { "description": "{feeds: [{id, title, description, url, sample_url, usd, refresh, cadence_minutes, sections, sources, latest_edition, latest_items}], parameters, pricing, how}." } } } }, "/api/v1/feeds/news": { "get": { "operationId": "getFeedNews", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "summary": "Consolidated news by topic — The newest pre-built edition of a data feed, over x402. A bare GET (no query, no payment header) answers the 402 challenge with the discovery document inside. With query parameters (section, q, ticker, date, at, limit) the edition is resolved and filtered FIRST: no edition yet, or filters that match nothing, answer free (charged: false). Otherwise 402, sign, repeat with the payment header.", "security": [], "parameters": [ { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One section only (see the catalogue). For news, `topic` is accepted too." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 }, "description": "Keep items containing this text." }, { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keep items about this ticker/symbol." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Keep items dated that UTC day." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Read a past edition (RFC 3339, or YYYY-MM-DD for that day's last edition)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Items per section (default 25 across all sections, 200 for one section)." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{feed, title, as_of, edition, next_edition, cadence_minutes, count, filters, sections: {name: [items]}, sources: [{name, ok, items}], paid block + settlement header} — or a free answer with charged: false when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in." }, "400": { "description": "Invalid parameters with a payment header present — refused before the facilitator is asked, naming the accepted parameters. Without a payment header the 402 quotes the price instead." }, "404": { "description": "Unknown feed, or no edition exists yet / at that time — nothing is owed." } } }, "post": { "operationId": "postFeedNews", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "summary": "Consolidated news by topic — Same as GET with the filters as a JSON body (empty body = the whole newest edition).", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string" }, "q": { "type": "string", "maxLength": 80 }, "ticker": { "type": "string" }, "date": { "type": "string", "format": "date" }, "at": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "The filtered edition plus the paid block, or a free answer (charged: false) when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Invalid parameters with a payment header present." }, "404": { "description": "Unknown feed, or no edition yet — nothing is owed." } } } }, "/api/v1/feeds/movers": { "get": { "operationId": "getFeedMovers", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "summary": "Market movers with reasons — The newest pre-built edition of a data feed, over x402. A bare GET (no query, no payment header) answers the 402 challenge with the discovery document inside. With query parameters (section, q, ticker, date, at, limit) the edition is resolved and filtered FIRST: no edition yet, or filters that match nothing, answer free (charged: false). Otherwise 402, sign, repeat with the payment header.", "security": [], "parameters": [ { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One section only (see the catalogue). For news, `topic` is accepted too." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 }, "description": "Keep items containing this text." }, { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keep items about this ticker/symbol." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Keep items dated that UTC day." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Read a past edition (RFC 3339, or YYYY-MM-DD for that day's last edition)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Items per section (default 25 across all sections, 200 for one section)." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{feed, title, as_of, edition, next_edition, cadence_minutes, count, filters, sections: {name: [items]}, sources: [{name, ok, items}], paid block + settlement header} — or a free answer with charged: false when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in." }, "400": { "description": "Invalid parameters with a payment header present — refused before the facilitator is asked, naming the accepted parameters. Without a payment header the 402 quotes the price instead." }, "404": { "description": "Unknown feed, or no edition exists yet / at that time — nothing is owed." } } }, "post": { "operationId": "postFeedMovers", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "summary": "Market movers with reasons — Same as GET with the filters as a JSON body (empty body = the whole newest edition).", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string" }, "q": { "type": "string", "maxLength": 80 }, "ticker": { "type": "string" }, "date": { "type": "string", "format": "date" }, "at": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "The filtered edition plus the paid block, or a free answer (charged: false) when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Invalid parameters with a payment header present." }, "404": { "description": "Unknown feed, or no edition yet — nothing is owed." } } } }, "/api/v1/feeds/filings": { "get": { "operationId": "getFeedFilings", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "summary": "SEC filings digest — The newest pre-built edition of a data feed, over x402. A bare GET (no query, no payment header) answers the 402 challenge with the discovery document inside. With query parameters (section, q, ticker, date, at, limit) the edition is resolved and filtered FIRST: no edition yet, or filters that match nothing, answer free (charged: false). Otherwise 402, sign, repeat with the payment header.", "security": [], "parameters": [ { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One section only (see the catalogue). For news, `topic` is accepted too." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 }, "description": "Keep items containing this text." }, { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keep items about this ticker/symbol." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Keep items dated that UTC day." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Read a past edition (RFC 3339, or YYYY-MM-DD for that day's last edition)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Items per section (default 25 across all sections, 200 for one section)." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{feed, title, as_of, edition, next_edition, cadence_minutes, count, filters, sections: {name: [items]}, sources: [{name, ok, items}], paid block + settlement header} — or a free answer with charged: false when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in." }, "400": { "description": "Invalid parameters with a payment header present — refused before the facilitator is asked, naming the accepted parameters. Without a payment header the 402 quotes the price instead." }, "404": { "description": "Unknown feed, or no edition exists yet / at that time — nothing is owed." } } }, "post": { "operationId": "postFeedFilings", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "summary": "SEC filings digest — Same as GET with the filters as a JSON body (empty body = the whole newest edition).", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string" }, "q": { "type": "string", "maxLength": 80 }, "ticker": { "type": "string" }, "date": { "type": "string", "format": "date" }, "at": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "The filtered edition plus the paid block, or a free answer (charged: false) when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Invalid parameters with a payment header present." }, "404": { "description": "Unknown feed, or no edition yet — nothing is owed." } } } }, "/api/v1/feeds/calendar": { "get": { "operationId": "getFeedCalendar", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] }, "summary": "Economic and earnings calendar — The newest pre-built edition of a data feed, over x402. A bare GET (no query, no payment header) answers the 402 challenge with the discovery document inside. With query parameters (section, q, ticker, date, at, limit) the edition is resolved and filtered FIRST: no edition yet, or filters that match nothing, answer free (charged: false). Otherwise 402, sign, repeat with the payment header.", "security": [], "parameters": [ { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One section only (see the catalogue). For news, `topic` is accepted too." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 }, "description": "Keep items containing this text." }, { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keep items about this ticker/symbol." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Keep items dated that UTC day." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Read a past edition (RFC 3339, or YYYY-MM-DD for that day's last edition)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Items per section (default 25 across all sections, 200 for one section)." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{feed, title, as_of, edition, next_edition, cadence_minutes, count, filters, sections: {name: [items]}, sources: [{name, ok, items}], paid block + settlement header} — or a free answer with charged: false when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in." }, "400": { "description": "Invalid parameters with a payment header present — refused before the facilitator is asked, naming the accepted parameters. Without a payment header the 402 quotes the price instead." }, "404": { "description": "Unknown feed, or no edition exists yet / at that time — nothing is owed." } } }, "post": { "operationId": "postFeedCalendar", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] }, "summary": "Economic and earnings calendar — Same as GET with the filters as a JSON body (empty body = the whole newest edition).", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string" }, "q": { "type": "string", "maxLength": 80 }, "ticker": { "type": "string" }, "date": { "type": "string", "format": "date" }, "at": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "The filtered edition plus the paid block, or a free answer (charged: false) when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Invalid parameters with a payment header present." }, "404": { "description": "Unknown feed, or no edition yet — nothing is owed." } } } }, "/api/v1/feeds/prediction-markets": { "get": { "operationId": "getFeedPredictionMarkets", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] }, "summary": "Prediction market board — The newest pre-built edition of a data feed, over x402. A bare GET (no query, no payment header) answers the 402 challenge with the discovery document inside. With query parameters (section, q, ticker, date, at, limit) the edition is resolved and filtered FIRST: no edition yet, or filters that match nothing, answer free (charged: false). Otherwise 402, sign, repeat with the payment header.", "security": [], "parameters": [ { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One section only (see the catalogue). For news, `topic` is accepted too." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 }, "description": "Keep items containing this text." }, { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keep items about this ticker/symbol." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Keep items dated that UTC day." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Read a past edition (RFC 3339, or YYYY-MM-DD for that day's last edition)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Items per section (default 25 across all sections, 200 for one section)." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{feed, title, as_of, edition, next_edition, cadence_minutes, count, filters, sections: {name: [items]}, sources: [{name, ok, items}], paid block + settlement header} — or a free answer with charged: false when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in." }, "400": { "description": "Invalid parameters with a payment header present — refused before the facilitator is asked, naming the accepted parameters. Without a payment header the 402 quotes the price instead." }, "404": { "description": "Unknown feed, or no edition exists yet / at that time — nothing is owed." } } }, "post": { "operationId": "postFeedPredictionMarkets", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] }, "summary": "Prediction market board — Same as GET with the filters as a JSON body (empty body = the whole newest edition).", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string" }, "q": { "type": "string", "maxLength": 80 }, "ticker": { "type": "string" }, "date": { "type": "string", "format": "date" }, "at": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "The filtered edition plus the paid block, or a free answer (charged: false) when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Invalid parameters with a payment header present." }, "404": { "description": "Unknown feed, or no edition yet — nothing is owed." } } } }, "/api/v1/feeds/ai": { "get": { "operationId": "getFeedAi", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] }, "summary": "AI changelog — The newest pre-built edition of a data feed, over x402. A bare GET (no query, no payment header) answers the 402 challenge with the discovery document inside. With query parameters (section, q, ticker, date, at, limit) the edition is resolved and filtered FIRST: no edition yet, or filters that match nothing, answer free (charged: false). Otherwise 402, sign, repeat with the payment header.", "security": [], "parameters": [ { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One section only (see the catalogue). For news, `topic` is accepted too." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 }, "description": "Keep items containing this text." }, { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keep items about this ticker/symbol." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Keep items dated that UTC day." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Read a past edition (RFC 3339, or YYYY-MM-DD for that day's last edition)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Items per section (default 25 across all sections, 200 for one section)." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{feed, title, as_of, edition, next_edition, cadence_minutes, count, filters, sections: {name: [items]}, sources: [{name, ok, items}], paid block + settlement header} — or a free answer with charged: false when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in." }, "400": { "description": "Invalid parameters with a payment header present — refused before the facilitator is asked, naming the accepted parameters. Without a payment header the 402 quotes the price instead." }, "404": { "description": "Unknown feed, or no edition exists yet / at that time — nothing is owed." } } }, "post": { "operationId": "postFeedAi", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] }, "summary": "AI changelog — Same as GET with the filters as a JSON body (empty body = the whole newest edition).", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string" }, "q": { "type": "string", "maxLength": 80 }, "ticker": { "type": "string" }, "date": { "type": "string", "format": "date" }, "at": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "The filtered edition plus the paid block, or a free answer (charged: false) when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Invalid parameters with a payment header present." }, "404": { "description": "Unknown feed, or no edition yet — nothing is owed." } } } }, "/api/v1/feeds/security": { "get": { "operationId": "getFeedSecurity", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] }, "summary": "Security advisories daily — The newest pre-built edition of a data feed, over x402. A bare GET (no query, no payment header) answers the 402 challenge with the discovery document inside. With query parameters (section, q, ticker, date, at, limit) the edition is resolved and filtered FIRST: no edition yet, or filters that match nothing, answer free (charged: false). Otherwise 402, sign, repeat with the payment header.", "security": [], "parameters": [ { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One section only (see the catalogue). For news, `topic` is accepted too." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 }, "description": "Keep items containing this text." }, { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keep items about this ticker/symbol." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Keep items dated that UTC day." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Read a past edition (RFC 3339, or YYYY-MM-DD for that day's last edition)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Items per section (default 25 across all sections, 200 for one section)." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{feed, title, as_of, edition, next_edition, cadence_minutes, count, filters, sections: {name: [items]}, sources: [{name, ok, items}], paid block + settlement header} — or a free answer with charged: false when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in." }, "400": { "description": "Invalid parameters with a payment header present — refused before the facilitator is asked, naming the accepted parameters. Without a payment header the 402 quotes the price instead." }, "404": { "description": "Unknown feed, or no edition exists yet / at that time — nothing is owed." } } }, "post": { "operationId": "postFeedSecurity", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] }, "summary": "Security advisories daily — Same as GET with the filters as a JSON body (empty body = the whole newest edition).", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string" }, "q": { "type": "string", "maxLength": 80 }, "ticker": { "type": "string" }, "date": { "type": "string", "format": "date" }, "at": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "The filtered edition plus the paid block, or a free answer (charged: false) when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Invalid parameters with a payment header present." }, "404": { "description": "Unknown feed, or no edition yet — nothing is owed." } } } }, "/api/v1/feeds/trending": { "get": { "operationId": "getFeedTrending", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] }, "summary": "What people are paying attention to — The newest pre-built edition of a data feed, over x402. A bare GET (no query, no payment header) answers the 402 challenge with the discovery document inside. With query parameters (section, q, ticker, date, at, limit) the edition is resolved and filtered FIRST: no edition yet, or filters that match nothing, answer free (charged: false). Otherwise 402, sign, repeat with the payment header.", "security": [], "parameters": [ { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One section only (see the catalogue). For news, `topic` is accepted too." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 }, "description": "Keep items containing this text." }, { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keep items about this ticker/symbol." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Keep items dated that UTC day." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Read a past edition (RFC 3339, or YYYY-MM-DD for that day's last edition)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Items per section (default 25 across all sections, 200 for one section)." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{feed, title, as_of, edition, next_edition, cadence_minutes, count, filters, sections: {name: [items]}, sources: [{name, ok, items}], paid block + settlement header} — or a free answer with charged: false when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in." }, "400": { "description": "Invalid parameters with a payment header present — refused before the facilitator is asked, naming the accepted parameters. Without a payment header the 402 quotes the price instead." }, "404": { "description": "Unknown feed, or no edition exists yet / at that time — nothing is owed." } } }, "post": { "operationId": "postFeedTrending", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] }, "summary": "What people are paying attention to — Same as GET with the filters as a JSON body (empty body = the whole newest edition).", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string" }, "q": { "type": "string", "maxLength": 80 }, "ticker": { "type": "string" }, "date": { "type": "string", "format": "date" }, "at": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "The filtered edition plus the paid block, or a free answer (charged: false) when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Invalid parameters with a payment header present." }, "404": { "description": "Unknown feed, or no edition yet — nothing is owed." } } } }, "/api/v1/feeds/regulation": { "get": { "operationId": "getFeedRegulation", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] }, "summary": "Regulation and enforcement feed — The newest pre-built edition of a data feed, over x402. A bare GET (no query, no payment header) answers the 402 challenge with the discovery document inside. With query parameters (section, q, ticker, date, at, limit) the edition is resolved and filtered FIRST: no edition yet, or filters that match nothing, answer free (charged: false). Otherwise 402, sign, repeat with the payment header.", "security": [], "parameters": [ { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One section only (see the catalogue). For news, `topic` is accepted too." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 }, "description": "Keep items containing this text." }, { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keep items about this ticker/symbol." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Keep items dated that UTC day." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Read a past edition (RFC 3339, or YYYY-MM-DD for that day's last edition)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Items per section (default 25 across all sections, 200 for one section)." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{feed, title, as_of, edition, next_edition, cadence_minutes, count, filters, sections: {name: [items]}, sources: [{name, ok, items}], paid block + settlement header} — or a free answer with charged: false when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in." }, "400": { "description": "Invalid parameters with a payment header present — refused before the facilitator is asked, naming the accepted parameters. Without a payment header the 402 quotes the price instead." }, "404": { "description": "Unknown feed, or no edition exists yet / at that time — nothing is owed." } } }, "post": { "operationId": "postFeedRegulation", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] }, "summary": "Regulation and enforcement feed — Same as GET with the filters as a JSON body (empty body = the whole newest edition).", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string" }, "q": { "type": "string", "maxLength": 80 }, "ticker": { "type": "string" }, "date": { "type": "string", "format": "date" }, "at": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "The filtered edition plus the paid block, or a free answer (charged: false) when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Invalid parameters with a payment header present." }, "404": { "description": "Unknown feed, or no edition yet — nothing is owed." } } } }, "/api/v1/feeds/crypto-listings": { "get": { "operationId": "getFeedCryptoListings", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "summary": "Crypto exchange listings and governance — The newest pre-built edition of a data feed, over x402. A bare GET (no query, no payment header) answers the 402 challenge with the discovery document inside. With query parameters (section, q, ticker, date, at, limit) the edition is resolved and filtered FIRST: no edition yet, or filters that match nothing, answer free (charged: false). Otherwise 402, sign, repeat with the payment header.", "security": [], "parameters": [ { "name": "section", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One section only (see the catalogue). For news, `topic` is accepted too." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 }, "description": "Keep items containing this text." }, { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keep items about this ticker/symbol." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Keep items dated that UTC day." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Read a past edition (RFC 3339, or YYYY-MM-DD for that day's last edition)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Items per section (default 25 across all sections, 200 for one section)." }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{feed, title, as_of, edition, next_edition, cadence_minutes, count, filters, sections: {name: [items]}, sources: [{name, ok, items}], paid block + settlement header} — or a free answer with charged: false when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in." }, "400": { "description": "Invalid parameters with a payment header present — refused before the facilitator is asked, naming the accepted parameters. Without a payment header the 402 quotes the price instead." }, "404": { "description": "Unknown feed, or no edition exists yet / at that time — nothing is owed." } } }, "post": { "operationId": "postFeedCryptoListings", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "summary": "Crypto exchange listings and governance — Same as GET with the filters as a JSON body (empty body = the whole newest edition).", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "section": { "type": "string" }, "q": { "type": "string", "maxLength": 80 }, "ticker": { "type": "string" }, "date": { "type": "string", "format": "date" }, "at": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "The filtered edition plus the paid block, or a free answer (charged: false) when nothing matched." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED)." }, "400": { "description": "Invalid parameters with a payment header present." }, "404": { "description": "Unknown feed, or no edition yet — nothing is owed." } } } }, "/api/v1/feeds/{feed}/sample": { "get": { "operationId": "sampleFeed", "summary": "Free: the edition from 24 hours ago, ten items per section (optionally one `section`). Shows the exact shape the paid edition has.", "security": [], "parameters": [ { "name": "feed", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "section", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The delayed edition with sample: true, delayed_hours and full_edition {url, usd, how}." }, "404": { "description": "Unknown feed, or no edition yet." } } } }, "/api/v1/x402/quote": { "get": { "operationId": "describeX402Quote", "summary": "Describe this x402 primitive. A bare GET on a paid resource answers the 402 challenge (never a bare doc page — that fails CDP's /validate preflight); the discovery document rides inside the 402 body.", "security": [], "responses": { "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in: endpoint, price, POST body shape, response shape, the x402 how, and the bazaar extension." }, "200": { "description": "Machine payments are not configured — the plain discovery document, nothing to sell." } } }, "post": { "operationId": "payForQuote", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "x402": {} } ] }, "summary": "Live quotes for up to 8 symbols (stocks, ETFs, crypto pairs as X-USD, FX as EURUSD=X), paid per call with x402 (≈ $0.01). No account is created; the answer is in the paid response.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "symbols" ], "properties": { "symbols": { "type": "array", "items": { "type": "string" }, "maxItems": 8 } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "Paid and answered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "price": { "type": "number" }, "change_pct": { "type": "number", "nullable": true }, "currency": { "type": "string" }, "source": { "type": "string" }, "as_of": { "type": "string" } } } }, "missing": { "type": "array", "items": { "type": "string" } }, "as_of": { "type": "string" }, "paid": { "type": "object" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected." }, "400": { "description": "Bad body — refused before any payment is taken." }, "409": { "description": "This settlement was already served." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/fetch": { "get": { "operationId": "describeX402Fetch", "summary": "Describe this x402 primitive. A bare GET on a paid resource answers the 402 challenge (never a bare doc page — that fails CDP's /validate preflight); the discovery document rides inside the 402 body.", "security": [], "responses": { "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED) with the discovery document merged in: endpoint, price, POST body shape, response shape, the x402 how, and the bazaar extension." }, "200": { "description": "Machine payments are not configured — the plain discovery document, nothing to sell." } } }, "post": { "operationId": "payForFetch", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "summary": "A public web page as readable text, or its links, or its SEO metadata — paid per call with x402 (≈ $0.02). Plain HTTP with a browser-grade fingerprint; JS-only or bot-walled pages come back flagged. Public hosts only; every redirect hop is screened. No account is created.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "extract": { "type": "string", "enum": [ "text", "links", "metadata" ] } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "Paid and answered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer" }, "final_url": { "type": "string" }, "extract": { "type": "string" }, "text": { "type": "string" }, "blocked": { "type": "boolean" }, "hops": { "type": "integer" }, "paid": { "type": "object" } } } } } }, "402": { "description": "Payment required (the quote), or a payment the facilitator rejected." }, "400": { "description": "Bad body — refused before any payment is taken." }, "409": { "description": "This settlement was already served." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/chat": { "post": { "operationId": "payForChat", "summary": "One language-model completion, paid per call — the same engine the swarm runs on, in the OpenAI messages shape. Up to 24 messages in and 1024 tokens out. ≈ $0.02 per call, no account, no key.", "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "maxItems": 24, "description": "OpenAI-style chat messages (roles system | user | assistant).", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant" ] }, "content": { "type": "string" } } } }, "max_tokens": { "type": "integer", "maximum": 1024, "description": "completion cap (server default if omitted)" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 } } } } } }, "parameters": [ { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1: the signed payment payload, base64." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v2: the signed payment payload, base64." } ], "responses": { "200": { "description": "{content, finish_reason, model, usage: {prompt_tokens, completion_tokens}, paid}." }, "402": { "description": "The payment requirements (v1 in the body, v2 in PAYMENT-REQUIRED), or a payment the facilitator rejected." }, "400": { "description": "Bad body — refused before any payment is taken." }, "409": { "description": "This settlement was already served." }, "503": { "description": "Machine payments are not configured." } } } }, "/api/v1/x402/supported": { "get": { "operationId": "getX402Supported", "summary": "Which x402 versions, schemes, networks, and extensions this resource speaks. Public.", "security": [], "responses": { "200": { "description": "Supported payment kinds and extensions." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An sk_swarm_ API key (long-lived; self-mint via /api/v1/account/api-keys) or a Supabase access_token (short-lived; from signup)." } }, "parameters": { "runId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The run id returned by POST /api/v1/runs." } }, "responses": { "Unauthorized": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such object (or not yours).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } } }, "AuthConfig": { "type": "object", "properties": { "provider": { "type": "string", "example": "supabase" }, "supabase_url": { "type": "string" }, "supabase_anon_key": { "type": "string" } } }, "AgentRegistration": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "agt_1a2b3c4d5e6f7080" }, "already_registered": { "type": "boolean" }, "next": { "type": "string" } } }, "AgentState": { "type": "object", "properties": { "user_id": { "type": "string" }, "agent_id": { "type": "string", "nullable": true }, "registered": { "type": "boolean" }, "signup_open": { "type": "boolean" } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "integer" }, "prefix": { "type": "string", "example": "sk_swarm_1a2b3c" }, "key": { "type": "string", "description": "The raw key — returned ONCE, hash-stored, unrecoverable." } } }, "RunCreate": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "description": "research | news | product | trips | trainer | finance | astrology | horoscope | …" }, "input": { "type": "string", "description": "Your question. Aliases: question | prompt | query | target. Astrology modes take constraint lines — see llms.txt." }, "max_workers": { "type": "integer", "description": "Optional parallelism override." } } }, "Run": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Report": { "type": "object", "properties": { "report_text": { "type": "string", "description": "The finished report body (markdown, with citations)." }, "rounds": { "type": "integer" }, "all_sources": { "type": "array", "items": { "type": "object" } } } }, "RouteDecision": { "type": "object", "properties": { "mode": { "type": "string" }, "confidence": { "type": "number" }, "from_llm": { "type": "boolean" } } }, "Account": { "type": "object", "properties": { "balance": { "type": "integer", "description": "Credit balance." }, "plan": { "type": "string" } } }, "LedgerEntry": { "type": "object", "properties": { "kind": { "type": "string" }, "amount": { "type": "integer" }, "note": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "CryptoTerms": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "network": { "type": "string", "example": "base" }, "chain_id": { "type": "integer", "example": 8453 }, "asset": { "type": "string", "example": "USDC" }, "contract": { "type": "string", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "pay_to": { "type": "string", "description": "The receiving address — present only when enabled." }, "min_usd": { "type": "number" }, "credits_per_usd": { "type": "number" }, "how": { "type": "string" } } }, "TopupResult": { "type": "object", "properties": { "credited": { "type": "boolean" }, "duplicate": { "type": "boolean" }, "credits": { "type": "integer" }, "balance": { "type": "integer" }, "usdc": { "type": "number" }, "confirmations": { "type": "integer" } } }, "BirthData": { "type": "object", "required": [ "date", "tz" ], "properties": { "date": { "type": "string", "example": "1990-06-15", "description": "YYYY-MM-DD" }, "time": { "type": "string", "example": "14:30", "description": "HH:MM local — optional; omit when unknown." }, "tz": { "type": "string", "example": "Europe/London", "description": "IANA name (use /api/v1/geo/tz to resolve coordinates → zone)." }, "city": { "type": "string", "example": "Leeds" }, "lat": { "type": "number", "example": 53.8 }, "lon": { "type": "number", "example": -1.55 } } }, "Pulse": { "type": "object", "required": [ "as_of", "prices", "news" ], "properties": { "as_of": { "type": "string", "format": "date-time" }, "free": { "type": "boolean", "description": "Always true." }, "symbols": { "type": "array", "items": { "type": "string" } }, "prices": { "type": "array", "items": { "type": "object", "required": [ "symbol", "price", "currency", "source", "as_of" ], "properties": { "symbol": { "type": "string" }, "price": { "type": "number" }, "change_pct": { "type": "number", "nullable": true, "description": "Session change in percent; null where the source has no session." }, "currency": { "type": "string" }, "source": { "type": "string", "description": "yahoo | pyth" }, "as_of": { "type": "string" } } } }, "prices_as_of": { "type": "string", "nullable": true }, "news": { "type": "object", "properties": { "digest": { "type": "object", "nullable": true, "description": "The newest published news digest, parsed: {title, as_of, report_url, stories:[{headline, link, source, excerpt}]}. Null when none ran in the last 36 hours." }, "headlines": { "type": "array", "items": { "type": "object", "description": "{headline, link, publisher, published, summary}" } }, "as_of": { "type": "string", "nullable": true } } }, "attribution": { "type": "string" }, "next": { "type": "object", "description": "How to get the same data over MCP and how to commission a real report." } } } } } }