{"openapi":"3.0.3","info":{"title":"Greenhead Labs","description":"Public pay-per-call XRPL data and Grok AI. No accounts, JWT, or sessions. Pay XRP or RLUSD on XRPL mainnet (xrpl:0), then retry with X-Payment-Txid set to the validated Payment hash.","version":"1.0.0","contact":{"name":"Greenhead Labs","url":"https://greenhead.io"}},"servers":[{"url":"https://x402.greenhead.io","description":"Public x402 origin"}],"security":[{"PaymentTxid":[]}],"tags":[{"name":"discovery","description":"Free crawler and agent files"},{"name":"xrpl","description":"Paid XRPL data"},{"name":"ai","description":"Paid Grok AI"}],"paths":{"/":{"get":{"operationId":"getHome","summary":"HTML index with SEO tags and endpoint list","security":[],"responses":{"200":{"description":"text/html endpoint index"}}}},"/.well-known/x402":{"get":{"operationId":"getX402Catalog","summary":"Free x402 service catalog","security":[],"responses":{"200":{"description":"Catalog of free and paid endpoints with prices and payTo."}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","summary":"Agent index (llmstxt.org v2)","security":[],"responses":{"200":{"description":"Markdown index of discovery files and paid APIs."}}}},"/agents.json":{"get":{"operationId":"getAgentsJson","summary":"Agent capability catalog (agents-txt.com)","security":[],"responses":{"200":{"description":"JSON: x402 on xrpl:0. No wallet addresses."}}}},"/health":{"get":{"operationId":"getHealth","summary":"Liveness","security":[],"responses":{"200":{"description":"{\"status\":\"ok\",\"network\":\"xrpl\"}"}}}},"/status":{"get":{"operationId":"getStatus","summary":"Readiness: network, XRPL RPC reachability, uptime, settle counters, version","security":[],"tags":["discovery"],"responses":{"200":{"description":"{\"ok\":true,\"network\":\"xrpl:0\",\"rpcReachable\":true,\"uptimeSeconds\":1,\"recentSettle\":{\"ok\":0,\"fail\":0},\"version\":\"1.0.0\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}}}}},"/v1/receipts/{txid}":{"get":{"operationId":"getReceiptByTxid","summary":"CFO receipt lookup by XRPL Payment hash (no payment required)","description":"Thin JSON contract: txid, redeemed, endpoint, payer, pay_to, amount_drops, internal, redeemed_at, status (settled|unused|unknown). Does not expose webhook secrets or keys.","security":[],"tags":["discovery"],"parameters":[{"name":"txid","in":"path","required":true,"description":"64-character XRPL transaction hash (hex, case-insensitive).","schema":{"type":"string","pattern":"^[A-Fa-f0-9]{64}$"}}],"responses":{"200":{"description":"Thin receipt. status=settled|unused|unknown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThinReceipt"}}}},"400":{"description":"txid is not a 64-character hex hash."}}}},"/api/metrics":{"get":{"operationId":"getMetrics","summary":"Paid-call meters (no payment required)","description":"as_of, paid_calls h24/d7/d30, revenue, unique_payers, by_endpoint, receipt_redeem_success_rate.","security":[],"tags":["discovery"],"responses":{"200":{"description":"CFO metrics JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metrics"}}}}}}},"/robots.txt":{"get":{"operationId":"getRobotsTxt","summary":"Robots allow-all","security":[],"responses":{"200":{"description":"text/plain Allow: /"}}}},"/sitemap.xml":{"get":{"operationId":"getSitemap","summary":"Sitemap of main endpoints","security":[],"responses":{"200":{"description":"XML sitemap"}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","summary":"This OpenAPI document","security":[],"responses":{"200":{"description":"OpenAPI 3.0 JSON."}}}},"/v1/xrpl/settlement":{"get":{"operationId":"settlement","summary":"Paid XRPL Payment attestation by query txid. Distinct from free GET /v1/receipts/:txid. Fail-closed: invalid, missing, unvalidated, or non-Payment hashes return 4xx without redeeming X-Payment-Txid. 75,000 drops (0.075 XRP).","description":"Paid XRPL Payment attestation by query txid. Distinct from free GET /v1/receipts/:txid. Fail-closed: invalid, missing, unvalidated, or non-Payment hashes return 4xx without redeeming X-Payment-Txid. 75,000 drops (0.075 XRP). Price: 0.075 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"txid","in":"query","required":true,"description":"64-character XRPL transaction hash to attest (required)","schema":{"type":"string"}},{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Settlement attestation JSON (locked shape). X-Payment-Txid is redeemed only after ledger checks pass. Body does not include `receipt`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementAttestation"}}}},"400":{"description":"Attestation failed before redeem: invalid_txid, not_validated, or not_payment. JSON {error, txid, success:false}. X-Payment-Txid is not consumed."},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"404":{"description":"settlement_not_found — no ledger transaction for query txid. JSON {error, txid, success:false}. X-Payment-Txid is not consumed."},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}}}},"/v1/xrpl/token":{"get":{"operationId":"token","summary":"Token info for an XRPL issued currency: issuer details, DEX/AMM price in XRP, holder metrics, and liquidity.","description":"Token info for an XRPL issued currency: issuer details, DEX/AMM price in XRP, holder metrics, and liquidity. Price: 0.01 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"issuer","in":"query","required":true,"description":"XRPL classic address of the token issuer (required)","schema":{"type":"string"}},{"name":"currency","in":"query","required":true,"description":"Currency code (3-char, hex, or UTF-8 name) (required)","schema":{"type":"string"}},{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}}}},"/v1/xrpl/listings":{"get":{"operationId":"listings","summary":"Recent XRPL token launches from GeckoTerminal / First Ledger, sorted by launch date descending.","description":"Recent XRPL token launches from GeckoTerminal / First Ledger, sorted by launch date descending. Price: 0.002 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Max listings to return (default 50, max 100)","schema":{"type":"string"}},{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}}}},"/v1/xrpl/orderbook":{"get":{"operationId":"orderbook","summary":"XRPL DEX order book for a currency pair (bids and asks, plus mid price).","description":"XRPL DEX order book for a currency pair (bids and asks, plus mid price). Price: 0.01 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"base","in":"query","required":true,"description":"Base asset: XRP or CODE:issuer / CODE.issuer / CODE+issuer (required)","schema":{"type":"string"}},{"name":"quote","in":"query","required":true,"description":"Quote asset: XRP or CODE:issuer / CODE.issuer / CODE+issuer (required)","schema":{"type":"string"}},{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}}}},"/v1/xrpl/portfolio":{"get":{"operationId":"portfolio","summary":"Wallet token holdings on XRPL, including XRP balance and estimated XRP values.","description":"Wallet token holdings on XRPL, including XRP balance and estimated XRP values. Price: 0.02 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"address","in":"query","required":true,"description":"XRPL classic address of the wallet (required)","schema":{"type":"string"}},{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}}}},"/v1/ai/chat":{"post":{"operationId":"ai_chat","summary":"Grok chat completions (model grok-3-mini) via https://api.x.ai/v1/chat/completions. Requires GROK_API_KEY.","description":"Grok chat completions (model grok-3-mini) via https://api.x.ai/v1/chat/completions. Requires GROK_API_KEY. Price: 0.05 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"string","description":"Chat messages array (required unless prompt is set)"},"prompt":{"type":"string","description":"Optional prompt string used as a single user message"}},"required":["messages"]}}}}}},"/v1/xrpl/amm-score":{"post":{"operationId":"amm_score","summary":"Fetch AMM pool data, then score pool quality 0-100 via Grok (grok-3-mini) for a sniper bot.","description":"Fetch AMM pool data, then score pool quality 0-100 via Grok (grok-3-mini) for a sniper bot. Price: 0.05 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"issuer":{"type":"string","description":"XRPL classic address of the token issuer (required)"},"currency":{"type":"string","description":"Currency code (3-char, hex, or UTF-8 name) (required)"},"poolXrp":{"type":"string","description":"Claimed XRP in the AMM pool (required)"}},"required":["issuer","currency","poolXrp"]}}}}}},"/v1/xrpl/trending":{"get":{"operationId":"trending","summary":"Top 10 XRPL tokens by 24h volume from xrpl.to.","description":"Top 10 XRPL tokens by 24h volume from xrpl.to. Price: 0.05 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}}}},"/v1/ai/trade-advice":{"post":{"operationId":"trade_advice","summary":"XRPL buy/skip/watch advice via Grok chat completions (grok-3-mini).","description":"XRPL buy/skip/watch advice via Grok chat completions (grok-3-mini). Price: 0.05 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"string","description":"Chat messages array (optional if prompt or token fields are set)"},"prompt":{"type":"string","description":"Optional prompt string describing the token or trade"}}}}}}}},"/v1/ai/risk-score":{"post":{"operationId":"risk_score","summary":"Fetch XRPL token data, then score risk 0-100 via Grok (grok-3-mini).","description":"Fetch XRPL token data, then score risk 0-100 via Grok (grok-3-mini). Price: 0.05 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"issuer":{"type":"string","description":"XRPL classic address of the token issuer (required)"},"currency":{"type":"string","description":"Currency code (required)"},"poolXrp":{"type":"string","description":"XRP in the AMM pool (required)"},"poolTokens":{"type":"string","description":"Token units in the AMM pool (required)"}},"required":["issuer","currency","poolXrp","poolTokens"]}}}}}},"/v1/ai/sentiment":{"post":{"operationId":"sentiment","summary":"Sentiment as positive/neutral/negative with a 0-100 confidence score via Grok (grok-3-mini).","description":"Sentiment as positive/neutral/negative with a 0-100 confidence score via Grok (grok-3-mini). Price: 0.05 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"Text to analyze (required)"}},"required":["text"]}}}}}},"/v1/ai/grok":{"post":{"operationId":"grok","summary":"Grok text via the xAI Responses API (default model grok-4.6). Requires GROK_API_KEY.","description":"Grok text via the xAI Responses API (default model grok-4.6). Requires GROK_API_KEY. Price: 0.05 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","description":"Prompt string or messages array (required unless prompt/messages is set)"},"prompt":{"type":"string","description":"Alias for input"},"messages":{"type":"string","description":"Chat messages array forwarded as input"},"model":{"type":"string","description":"Optional model name (default grok-4.6)"}},"required":["input"]}}}}}},"/v1/ai/image":{"post":{"operationId":"image","summary":"Generate an image with Grok Imagine. Requires GROK_API_KEY.","description":"Generate an image with Grok Imagine. Requires GROK_API_KEY. Price: 0.05 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"Image prompt (required)"},"model":{"type":"string","description":"Optional model (default grok-imagine-image-quality)"}},"required":["prompt"]}}}}}},"/v1/ai/video":{"post":{"operationId":"video","summary":"Start a Grok Imagine video generation. Requires GROK_API_KEY.","description":"Start a Grok Imagine video generation. Requires GROK_API_KEY. Price: 0.05 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"Video prompt (required)"},"model":{"type":"string","description":"Optional model (default grok-imagine-video)"}},"required":["prompt"]}}}}},"get":{"operationId":"video_status","summary":"Poll a Grok Imagine video job by request_id. Requires GROK_API_KEY.","description":"Poll a Grok Imagine video job by request_id. Requires GROK_API_KEY. Price: 0.05 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"request_id","in":"query","required":true,"description":"xAI video request_id (required unless passed as /v1/ai/video/:requestId)","schema":{"type":"string"}},{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}}}},"/v1/ai/tts":{"post":{"operationId":"tts","summary":"Grok text-to-speech. Returns audio. Requires GROK_API_KEY.","description":"Grok text-to-speech. Returns audio. Requires GROK_API_KEY. Price: 0.05 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"Text to speak (required)"},"voice_id":{"type":"string","description":"Optional voice (default eve)"},"language":{"type":"string","description":"Optional language (default en)"}},"required":["text"]}}}}}},"/v1/xrpl/wallet-score":{"post":{"operationId":"wallet_score","summary":"Wallet trust/risk score 0-100 from XRPL age, tx count, trust lines, and balance via Grok. 2000 drops.","description":"Wallet trust/risk score 0-100 from XRPL age, tx count, trust lines, and balance via Grok. 2000 drops. Price: 0.002 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"XRPL classic address (required)"}},"required":["address"]}}}}}},"/v1/xrpl/token-risk":{"post":{"operationId":"token_risk","summary":"Rug-pull probability from AMM liquidity, holder concentration, and issuer trust lines via Grok. 2000 drops.","description":"Rug-pull probability from AMM liquidity, holder concentration, and issuer trust lines via Grok. 2000 drops. Price: 0.002 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","description":"Token currency code (required)"},"issuer":{"type":"string","description":"XRPL classic address of the token issuer (required)"}},"required":["currency","issuer"]}}}}}},"/v1/grok/market-summary":{"post":{"operationId":"market_summary","summary":"Plain-English XRPL daily market digest from the top 10 GeckoTerminal pools via Grok. 3000 drops. Body optional.","description":"Plain-English XRPL daily market digest from the top 10 GeckoTerminal pools via Grok. 3000 drops. Body optional. Price: 0.003 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}}}},"/v1/base/ping":{"get":{"operationId":"base_ping","summary":"Prove route for Base mainnet USDC x402 (eip155:8453). HTTP 200 after facilitator verify+settle. Priced as the cheapest SKU (0.002 face → 2000 USDC atomic when Base is enabled).","description":"Prove route for Base mainnet USDC x402 (eip155:8453). HTTP 200 after facilitator verify+settle. Priced as the cheapest SKU (0.002 face → 2000 USDC atomic when Base is enabled). Price: 0.002 XRP or 0.01 RLUSD. Unpaid calls return HTTP 402.","security":[{"PaymentTxid":[]},{"PaymentSignature":[]}],"parameters":[{"name":"campaign","in":"query","required":false,"description":"Optional attribution tag copied onto the payment receipt (also accepted as XRPL DestinationTag or Payment memo).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid success. JSON objects include `receipt`. Header X-Payment-Receipt is base64 JSON of the same object.","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/PaymentReceipt"}}}}},"headers":{"X-Payment-Receipt":{"description":"Base64 JSON PaymentReceipt","schema":{"type":"string"}}}},"402":{"description":"Payment required or payment verification failed. JSON `error`/`code` is a stable PaymentErrorCode. Body and Payment-Required header include network, payTo, and accepts[].","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}},"504":{"description":"payment_timeout — XRPL RPC lookup timed out. Retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentError"}}}}}}}},"components":{"securitySchemes":{"PaymentTxid":{"type":"apiKey","in":"header","name":"X-Payment-Txid","description":"Validated XRPL Payment hash sent to catalog payTo. Single use. No JWT or API key."},"PaymentSignature":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"Official x402 PaymentPayload (base64 JSON) for Base USDC eip155:8453. Used when GHL_BASE_PAYTO is set (unless X402_BASE_ENABLED=0)."}},"schemas":{"PaymentErrorCode":{"type":"string","description":"Stable machine-readable payment error code.","enum":["payment_required","payment_lookup_failed","payment_underpaid","payment_wrong_payTo","payment_already_used","payment_not_validated","payment_pending","payment_timeout","payment_wallet_unconfigured","invalid_payment_txid","payment_hash_mismatch","payment_failed_on_ledger","not_a_payment","unsupported_asset","invalid_payment_signature","facilitator_auth_failed","facilitator_verify_failed","facilitator_settle_failed"]},"PaymentError":{"type":"object","required":["error","code","httpStatus","network"],"properties":{"error":{"$ref":"#/components/schemas/PaymentErrorCode"},"code":{"$ref":"#/components/schemas/PaymentErrorCode"},"httpStatus":{"type":"integer"},"retryable":{"type":"boolean"},"message":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"network":{"type":"string","example":"xrpl:0"},"payTo":{"type":"string","nullable":true},"txid":{"type":"string"}}},"PaymentReceipt":{"type":"object","required":["txid","endpoint","amount","asset","network","timestamp","payTo"],"properties":{"txid":{"type":"string","description":"Validated XRPL Payment hash (uppercase)."},"endpoint":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"},"name":{"type":"string"}}},"amount":{"type":"string","description":"Delivered amount (XRP decimal or RLUSD value)."},"asset":{"type":"string","enum":["XRP","RLUSD","USDC"]},"network":{"type":"string","example":"xrpl:0"},"timestamp":{"type":"string","format":"date-time"},"payTo":{"type":"string"},"campaign":{"type":"string","description":"Optional DestinationTag, memo, or ?campaign= query."}}},"ThinReceipt":{"type":"object","required":["txid","redeemed","endpoint","payer","pay_to","amount_drops","internal","redeemed_at","status"],"properties":{"txid":{"type":"string"},"redeemed":{"type":"boolean"},"endpoint":{"type":"string","nullable":true,"example":"GET /v1/xrpl/listings"},"payer":{"type":"string","nullable":true},"pay_to":{"type":"string","nullable":true},"amount_drops":{"type":"integer","nullable":true},"internal":{"type":"boolean"},"redeemed_at":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["settled","unused","unknown"]}}},"SettlementAttestation":{"type":"object","required":["txid","network","validated","ledger_index","success","transaction_type","from","to","destination_tag","amount","memos","attested_at","attestation_version"],"properties":{"txid":{"type":"string"},"network":{"type":"string","example":"xrpl:0"},"validated":{"type":"boolean","enum":[true]},"ledger_index":{"type":"integer"},"success":{"type":"boolean"},"transaction_type":{"type":"string","enum":["Payment"]},"from":{"type":"string"},"to":{"type":"string"},"destination_tag":{"type":"integer","nullable":true},"amount":{"oneOf":[{"type":"object","required":["asset","drops","xrp"],"properties":{"asset":{"type":"string","enum":["XRP"]},"drops":{"type":"string","example":"75000"},"xrp":{"type":"string","example":"0.075"}}},{"type":"object","required":["asset","issuer","value","currency"],"properties":{"asset":{"type":"string","enum":["RLUSD"]},"issuer":{"type":"string","example":"rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De"},"value":{"type":"string"},"currency":{"type":"string","enum":["RLUSD"]}}}]},"memos":{"type":"array","items":{"type":"object"}},"attested_at":{"type":"string","format":"date-time"},"attestation_version":{"type":"integer","enum":[1]}}},"Metrics":{"type":"object","required":["as_of","paid_calls","revenue","unique_payers","by_endpoint","receipt_redeem_success_rate"],"properties":{"as_of":{"type":"string","format":"date-time"},"paid_calls":{"type":"object","properties":{"h24":{"type":"integer"},"d7":{"type":"integer"},"d30":{"type":"integer"}}},"revenue":{"type":"object","properties":{"drops":{"type":"integer"},"xrp":{"type":"number"},"usd_mark":{"type":"number"},"mark_xrp_usd":{"type":"number"}}},"unique_payers":{"type":"object","properties":{"external":{"type":"integer"},"internal":{"type":"integer"}}},"by_endpoint":{"type":"array","items":{"type":"object","properties":{"endpoint":{"type":"string"},"calls":{"type":"integer"},"drops":{"type":"integer"}}}},"receipt_redeem_success_rate":{"type":"number"}}},"Status":{"type":"object","required":["ok","network","rpcReachable","uptimeSeconds","recentSettle"],"properties":{"ok":{"type":"boolean"},"network":{"type":"string","example":"xrpl:0"},"rpcReachable":{"type":"boolean"},"uptimeSeconds":{"type":"integer"},"recentSettle":{"type":"object","properties":{"ok":{"type":"integer"},"fail":{"type":"integer"}}},"version":{"type":"string"}}}}},"externalDocs":{"description":"HTML documentation","url":"https://x402.greenhead.io/docs"}}