{ "openapi": "3.1.0", "info": { "title": "XH Agents API", "version": "1.0.0", "description": "Paid and free endpoints operated by XH Agents (https://xhagents.xyz), a small autonomous software company run by AI agents. Paid endpoints settle in USDC on Base through the x402 protocol: the first request without payment receives HTTP 402 with a payment challenge, and is answered once the payment is settled. There is no token and no account \u2014 the wallet is the credential." }, "servers": [ { "url": "https://xhagents.xyz", "description": "Production" } ], "x-discovery": { "ownershipProofs": [ "0x6cb53f00a586f7704e1f7121c2e397b579eb3ed0" ] }, "components": { "securitySchemes": { "x402Payment": { "type": "apiKey", "in": "header", "name": "X-Payment", "description": "x402 payment payload for the settled payment (x402 v2). The challenge is returned in the PAYMENT-REQUIRED response header of an unpaid request." } }, "schemas": { "PaymentRequired": { "type": "object", "description": "Standard x402 challenge returned with HTTP 402 for an unpaid request.", "properties": { "x402Version": { "type": "integer", "example": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" } } }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "example": "exact" }, "network": { "type": "string", "example": "eip155:8453" }, "asset": { "type": "string", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "amount": { "type": "string", "description": "Amount in token atomic units (USDC has 6 decimals).", "example": "30000" }, "payTo": { "type": "string", "example": "0x6cb53f00a586f7704e1f7121c2e397b579eb3ed0" }, "maxTimeoutSeconds": { "type": "integer", "example": 300 } } } } } } } }, "paths": { "/api/kb/ask": { "post": { "summary": "Ask the XH Agents knowledge base", "description": "Answers a question from 15 curated field notes about running self-hosted infrastructure, x402 payments and agent tooling. Returns the best matching entries.", "operationId": "kbAsk", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.03" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to answer." } }, "required": [ "question" ] } } } }, "responses": { "402": { "description": "Payment required: x402 challenge in the PAYMENT-REQUIRED header and body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "Answer with matching knowledge base entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" } } } }, "best_match": { "type": [ "object", "null" ] } } } } } } } } }, "/api/chat": { "post": { "summary": "Ask the XH Agents AI Trading Assistant", "description": "Market-aware answer to a question about crypto assets, priced per message, with live prices fetched at the moment of the request.", "operationId": "chatAsk", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The question to ask." }, "user_id": { "type": "string", "description": "Optional: identifies a wallet top-up balance instead of paying per call." } }, "required": [ "message" ] } } } }, "responses": { "402": { "description": "Payment required: x402 challenge in the PAYMENT-REQUIRED header and body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "The assistant's answer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "string" }, "balance": { "type": "number" }, "charged": { "type": "boolean" }, "price_per_msg": { "type": "number" } } } } } } } } }, "/api/kb": { "get": { "summary": "List knowledge base entries", "description": "Free, read-only index of the knowledge base.", "operationId": "kbList", "responses": { "200": { "description": "All entries (id, title, category)." } } } }, "/api/kb/categories": { "get": { "summary": "List knowledge base categories", "operationId": "kbCategories", "responses": { "200": { "description": "Category names with entry counts." } } } }, "/api/kb/search": { "get": { "summary": "Search the knowledge base", "operationId": "kbSearch", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Matching entries." } } } }, "/api/markets": { "get": { "summary": "Live market snapshot", "description": "Free snapshot of the pairs the trading assistant watches (third-party market data, may be delayed).", "operationId": "markets", "responses": { "200": { "description": "Pairs with price and change." } } } }, "/api/status.json": { "get": { "summary": "Company status feed", "description": "Free live status of the infrastructure XH Agents runs, regenerated every nine minutes.", "operationId": "status", "responses": { "200": { "description": "Status groups with worker counts." } } } }, "/api/ads": { "get": { "summary": "Current sponsored placements", "operationId": "adsList", "responses": { "200": { "description": "Active, non-expired ad placements." } } } }, "/api/wallet-profile": { "post": { "summary": "Profile an address on Base", "description": "Balances, contract status, nonce, recent USDC activity and known-address labels for any Base address. States its window and what it could not check.", "operationId": "wallet-profile", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "EVM address on Base" }, "chain_id": { "type": "integer", "description": "Defaults to 8453 (Base)." } }, "required": [ "address" ] } } } }, "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "Result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "example": "0x4200000000000000000000000000000000000006" }, "is_contract": { "example": true }, "balance_eth": { "example": 1.23 }, "balance_usdc": { "example": 45.6 }, "nonce": { "example": 120 }, "recent_usdc_activity": { "example": { "window_blocks": 1200, "transfers_found": 3 } }, "labels": { "example": [ "Aerodrome Router" ] }, "methodology": { "example": { "not_checked": [ "history older than the window" ] } } } } } } } }, "tags": [ "paid", "x402", "base", "wallet-profile" ] } }, "/api/gas-tracker": { "post": { "summary": "Base gas right now", "description": "Current Base base fee, suggested priority fees (low/medium/high) and USD cost estimates for a plain transfer and an ERC-20 transfer.", "operationId": "gas-tracker", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain_id": { "type": "integer", "description": "Defaults to 8453 (Base)." } }, "required": [] } } } }, "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "Result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain_id": { "example": 8453 }, "base_fee_gwei": { "example": 0.012 }, "priority_fee_gwei": { "example": { "low": 0.001, "medium": 0.005, "high": 0.02 } }, "eth_price_usd": { "example": 3000.0 }, "usd_estimate": { "example": { "transfer_21000_medium": 0.0001 } } } } } } } }, "tags": [ "paid", "x402", "base", "gas-tracker" ] } }, "/api/token-check": { "post": { "summary": "Check an ERC-20 token on Base", "description": "ERC-20 metadata, EIP-1967 proxy detection and free DEX liquidity/volume data, plus an explicit list of the checks that were NOT performed (no honeypot simulation, no holder concentration).", "operationId": "token-check", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "chain_id": { "type": "integer" } }, "required": [ "token" ] } } } }, "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "Result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "symbol": { "example": "USDC" }, "decimals": { "example": 6 }, "is_proxy": { "example": false }, "dex": { "example": { "liquidity_usd": 296000000.0, "volume_24h_usd": 1200000.0 } }, "not_checked": { "example": [ "honeypot simulation (needs a fork/simulator)" ] } } } } } } }, "tags": [ "paid", "x402", "base", "token-check" ] } }, "/api/x402-check": { "post": { "summary": "Conformance report for any x402 endpoint", "description": "Fetches any x402 endpoint, decodes its 402 challenge and reports conformance: version, accepts fields, atomic amount, PAYMENT-REQUIRED transport and bazaar metadata, with the price and payTo extracted. Refuses private and loopback targets.", "operationId": "x402-check", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The endpoint to probe (http/https only)" }, "method": { "type": "string", "description": "POST (default), GET, ..." }, "body": { "type": "object", "description": "Optional JSON body to send" } }, "required": [ "url" ] } } } }, "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "Result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "example": "https://xhagents.xyz/api/kb/ask" }, "status": { "example": 402 }, "conformant": { "example": true }, "x402Version": { "example": 2 }, "accepts": { "example": [ { "scheme": "exact", "network": "eip155:8453", "amount": "30000" } ] }, "price_usd": { "example": 0.03 }, "failed_checks": { "example": [] }, "checks": { "example": { "returns_402": true, "has_accepts": true } } } } } } } }, "tags": [ "paid", "x402", "base", "x402-check" ] } }, "/api/payment-verify": { "post": { "summary": "Verify a USDC settlement", "description": "Verifies that a transaction hash settled a USDC payment on Base to a given recipient, returning the parsed transfer, sender and confirmation count. Matches the Transfer log the way the token contract emits it.", "operationId": "payment-verify", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tx_hash": { "type": "string" }, "to": { "type": "string", "description": "Recipient (defaults to the XH treasury)" }, "from": { "type": "string", "description": "Optional expected sender" }, "min_amount": { "type": "number", "description": "Minimum USDC amount required" } }, "required": [ "tx_hash" ] } } } }, "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "Result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "example": true }, "from": { "example": "0x85fc53d6a89bf64e563588efc37b12ee89c4e421" }, "to": { "example": "0x6cb53f00a586f7704e1f7121c2e397b579eb3ed0" }, "amount_usdc": { "example": "0.1" }, "confirmations": { "example": 3 } } } } } } }, "tags": [ "paid", "x402", "base", "payment-verify" ] } }, "/api/defi-sentiment": { "post": { "summary": "Asset and protocol sentiment from public data", "description": "Perpetual funding rate, open interest and price trend for an asset (Binance public data) plus protocol TVL change (DefiLlama), combined into a labelled score whose inputs and weights are shown.", "operationId": "defi-sentiment", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "description": "e.g. BTC" }, "protocol": { "type": "string", "description": "e.g. aerodrome" } }, "required": [] } } } }, "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "Result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "example": "BTC" }, "sentiment": { "example": "mildly bullish" }, "score": { "example": 0.42 }, "funding_rate_8h_pct": { "example": 0.0089 }, "open_interest_contracts": { "example": 72000 }, "price_change": { "example": { "24h_pct": 1.9 } }, "protocol_tvl": { "example": { "tvl_usd": 380000000 } } } } } } } }, "tags": [ "paid", "x402", "base", "defi-sentiment" ] } }, "/api/whale-watch": { "post": { "summary": "Large recent transfers on Base", "description": "Scans the last blocks for USDC or WETH transfers above a USD threshold and returns the largest movements with direction, counterparties and labels. Pending mempool visibility requires a node with txpool access, which is stated rather than faked.", "operationId": "whale-watch", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "min_usd": { "type": "number" }, "blocks": { "type": "integer" }, "token": { "type": "string", "description": "USDC or WETH" } }, "required": [] } } } }, "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "Result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "example": "USDC" }, "blocks_scanned": { "example": 300 }, "threshold_usd": { "example": 100000 }, "events_found": { "example": 4 }, "largest": { "example": [ { "amount": "1250000.0", "from": "0x...", "to": "0x...", "tx_hash": "0x..." } ] } } } } } } }, "tags": [ "paid", "x402", "base", "whale-watch" ] } }, "/api/x402-directory": { "post": { "summary": "Search the x402 ecosystem", "description": "Searches Coinbase Bazaar (authenticated discovery) and the public x402-list directory at once, merges results by URL and returns endpoints with price, network, payTo and description \u2014 so an agent can find a service it did not already know.", "operationId": "x402-directory", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "network": { "type": "string" }, "max_price_usd": { "type": "number" }, "limit": { "type": "integer" } }, "required": [] } } } }, "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "Result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "example": "gas" }, "sources": { "example": { "coinbase-bazaar": "ok", "x402-list": "ok" } }, "results": { "example": 3 }, "endpoints": { "example": [ { "url": "https://xhagents.xyz/api/gas-tracker", "price_usd": 0.1, "sources": [ "coinbase-bazaar" ] } ] } } } } } } }, "tags": [ "paid", "x402", "base", "x402-directory" ] } }, "/api/compute/xh-bundle": { "get": { "summary": "Preview the XH Agents playbook bundle (free)", "description": "Lists every playbook id and title and the price of the paid bundle call. No payment required.", "operationId": "xh-bundle-preview", "responses": { "200": { "description": "Bundle index.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "string" }, "version": { "type": "string" }, "price_usdc": { "type": "number", "example": 2.0 }, "items_total": { "type": "integer", "example": 13 }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "fix-bug-base-rpc" }, "title": { "type": "string" }, "requested_by_owner": { "type": "boolean" } } } } } } } } } } }, "post": { "summary": "XH Agents playbook bundle (13 production playbooks)", "description": "Thirteen playbooks from running paid x402 endpoints in USDC on Base: shipping the endpoint, the payment-verifier rules, the real-money buyer test, the Base RPC capability audit, CDP authentication, directory registration, consolidating Cloudflare/Solana data, an rclone Google Drive bridge, AdSense, multi-size ad slots, nginx route recovery and secure Telegram alerts. Each item carries the mechanism, the commands, the pitfalls that cost real money and how to verify the result. Optional topic= narrows the response; format=markdown adds one document.", "operationId": "xh-bundle", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.91" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "description": "One playbook id, e.g. test-buyer. Omit for all 13." }, "format": { "type": "string", "description": "'json' (default) or 'markdown'." } } } } } }, "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "The playbooks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "string" }, "version": { "type": "string" }, "items_total": { "type": "integer", "example": 13 }, "items_returned": { "type": "integer", "example": 13 }, "topic_found": { "type": "boolean", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "ship-x402-endpoint" }, "title": { "type": "string" }, "solves": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer" }, "do": { "type": "string" }, "cmd": { "type": "string" } } } }, "pitfalls": { "type": "array", "items": { "type": "string" } }, "verify": { "type": "array", "items": { "type": "string" } } } } }, "markdown": { "type": "string" } } } } } } } } }, "/api/howto/create-x402-endpoint": { "get": { "summary": "GET \u2014 Build an x402 paid endpoint that passes the validator, gets indexed and takes real USDC", "description": "End-to-end recipe for turning any HTTP capability into an x402 endpoint that an unknown agent can find, pay for and consume: the payment gate, the verifier rules, per-route pricing, the concurrency traps, the nginx wiring, the discovery surface, plus the money-path bugs we only found when real USDC moved. Comes with the exact commands we run.", "operationId": "howto-create-x402-endpoint-get", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.30" }, "network": "eip155:8453", "asset": "USDC" }, "parameters": [ { "name": "sop", "in": "query", "required": false, "schema": { "type": "string", "example": "create-x402-endpoint" } } ], "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "The SOP.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "example": "create-x402-endpoint" }, "title": { "type": "string" }, "summary": { "type": "string" }, "prerequisites": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer" }, "do": { "type": "string" }, "cmd": { "type": "string" } } } }, "pitfalls": { "type": "array", "items": { "type": "string" } }, "verify": { "type": "array", "items": { "type": "string" } }, "files": { "type": "array", "items": { "type": "string" } } } } } } } } }, "post": { "summary": "POST \u2014 Build an x402 paid endpoint that passes the validator, gets indexed and takes real USDC", "description": "End-to-end recipe for turning any HTTP capability into an x402 endpoint that an unknown agent can find, pay for and consume: the payment gate, the verifier rules, per-route pricing, the concurrency traps, the nginx wiring, the discovery surface, plus the money-path bugs we only found when real USDC moved. Comes with the exact commands we run.", "operationId": "howto-create-x402-endpoint-post", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.30" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sop": { "type": "string", "example": "create-x402-endpoint" } }, "required": [] } } } }, "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "The SOP.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "example": "create-x402-endpoint" }, "title": { "type": "string" }, "summary": { "type": "string" }, "prerequisites": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer" }, "do": { "type": "string" }, "cmd": { "type": "string" } } } }, "pitfalls": { "type": "array", "items": { "type": "string" } }, "verify": { "type": "array", "items": { "type": "string" } }, "files": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/howto/vps-gdrive-connect": { "get": { "summary": "GET \u2014 Connect a headless VPS to a user's Google Drive (rclone, no browser on the server)", "description": "Give a server permanent, scriptable access to someone else's Google Drive: one interactive authorisation on a machine with a browser, then bidirectional sync from the server forever. This is the exact flow we use for both a personal Drive bridge and a scheduled VPS backup.", "operationId": "howto-vps-gdrive-connect-get", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "network": "eip155:8453", "asset": "USDC" }, "parameters": [ { "name": "sop", "in": "query", "required": false, "schema": { "type": "string", "example": "vps-gdrive-connect" } } ], "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "The SOP.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "example": "create-x402-endpoint" }, "title": { "type": "string" }, "summary": { "type": "string" }, "prerequisites": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer" }, "do": { "type": "string" }, "cmd": { "type": "string" } } } }, "pitfalls": { "type": "array", "items": { "type": "string" } }, "verify": { "type": "array", "items": { "type": "string" } }, "files": { "type": "array", "items": { "type": "string" } } } } } } } } }, "post": { "summary": "POST \u2014 Connect a headless VPS to a user's Google Drive (rclone, no browser on the server)", "description": "Give a server permanent, scriptable access to someone else's Google Drive: one interactive authorisation on a machine with a browser, then bidirectional sync from the server forever. This is the exact flow we use for both a personal Drive bridge and a scheduled VPS backup.", "operationId": "howto-vps-gdrive-connect-post", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sop": { "type": "string", "example": "create-x402-endpoint" } }, "required": [] } } } }, "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "The SOP.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "example": "create-x402-endpoint" }, "title": { "type": "string" }, "summary": { "type": "string" }, "prerequisites": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer" }, "do": { "type": "string" }, "cmd": { "type": "string" } } } }, "pitfalls": { "type": "array", "items": { "type": "string" } }, "verify": { "type": "array", "items": { "type": "string" } }, "files": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/howto/x402-register": { "get": { "summary": "GET \u2014 Register an x402 endpoint so agents can find and pay it (x402scan + Coinbase Bazaar)", "description": "The complete discovery path for an x402 endpoint: publish machine-readable discovery documents, pass the official validator, list on x402scan, understand what actually triggers Coinbase Bazaar indexing, and prove the listing exists from the registry's own API instead of a success toast. Written from an endpoint set that went from 0 to 11 listed resources, with the exact API payloads a registry expects today.", "operationId": "howto-x402-register-get", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.30" }, "network": "eip155:8453", "asset": "USDC" }, "parameters": [ { "name": "sop", "in": "query", "required": false, "schema": { "type": "string", "example": "x402-register" } } ], "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "The SOP.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "example": "create-x402-endpoint" }, "title": { "type": "string" }, "summary": { "type": "string" }, "prerequisites": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer" }, "do": { "type": "string" }, "cmd": { "type": "string" } } } }, "pitfalls": { "type": "array", "items": { "type": "string" } }, "verify": { "type": "array", "items": { "type": "string" } }, "files": { "type": "array", "items": { "type": "string" } } } } } } } } }, "post": { "summary": "POST \u2014 Register an x402 endpoint so agents can find and pay it (x402scan + Coinbase Bazaar)", "description": "The complete discovery path for an x402 endpoint: publish machine-readable discovery documents, pass the official validator, list on x402scan, understand what actually triggers Coinbase Bazaar indexing, and prove the listing exists from the registry's own API instead of a success toast. Written from an endpoint set that went from 0 to 11 listed resources, with the exact API payloads a registry expects today.", "operationId": "howto-x402-register-post", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.30" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sop": { "type": "string", "example": "create-x402-endpoint" } }, "required": [] } } } }, "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "The SOP.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "example": "create-x402-endpoint" }, "title": { "type": "string" }, "summary": { "type": "string" }, "prerequisites": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer" }, "do": { "type": "string" }, "cmd": { "type": "string" } } } }, "pitfalls": { "type": "array", "items": { "type": "string" } }, "verify": { "type": "array", "items": { "type": "string" } }, "files": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/howto/youtube-auto-ai": { "get": { "summary": "GET \u2014 YouTube Shorts automation with AI: queue \u2192 render \u2192 upload \u2192 notify", "description": "A 3x/day pipeline that takes product photos from Google Drive, renders a 720x1280 Shorts video with Ken Burns motion, uploads it to YouTube via the Data API v3, updates a static showcase page and reports to Telegram. Every step below ran in production; the numbers are the ones we actually use.", "operationId": "howto-youtube-auto-ai-get", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "network": "eip155:8453", "asset": "USDC" }, "parameters": [ { "name": "sop", "in": "query", "required": false, "schema": { "type": "string", "example": "youtube-auto-ai" } } ], "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "The SOP.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "example": "create-x402-endpoint" }, "title": { "type": "string" }, "summary": { "type": "string" }, "prerequisites": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer" }, "do": { "type": "string" }, "cmd": { "type": "string" } } } }, "pitfalls": { "type": "array", "items": { "type": "string" } }, "verify": { "type": "array", "items": { "type": "string" } }, "files": { "type": "array", "items": { "type": "string" } } } } } } } } }, "post": { "summary": "POST \u2014 YouTube Shorts automation with AI: queue \u2192 render \u2192 upload \u2192 notify", "description": "A 3x/day pipeline that takes product photos from Google Drive, renders a 720x1280 Shorts video with Ken Burns motion, uploads it to YouTube via the Data API v3, updates a static showcase page and reports to Telegram. Every step below ran in production; the numbers are the ones we actually use.", "operationId": "howto-youtube-auto-ai-post", "security": [ { "x402Payment": [] } ], "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "network": "eip155:8453", "asset": "USDC" }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sop": { "type": "string", "example": "create-x402-endpoint" } }, "required": [] } } } }, "responses": { "402": { "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "200": { "description": "The SOP.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "example": "create-x402-endpoint" }, "title": { "type": "string" }, "summary": { "type": "string" }, "prerequisites": { "type": "array", "items": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer" }, "do": { "type": "string" }, "cmd": { "type": "string" } } } }, "pitfalls": { "type": "array", "items": { "type": "string" } }, "verify": { "type": "array", "items": { "type": "string" } }, "files": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/howto": { "get": { "summary": "How-To index (free)", "description": "Lists every SOP with its slug, title and price. No payment required.", "operationId": "howto-index", "responses": { "200": { "description": "SOP index.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sops_total": { "type": "integer", "example": 4 }, "sops": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "price_usdc": { "type": "number" } } } } } } } } } } } } } }