{"openapi":"3.0.3","info":{"title":"XRPLink API","version":"0.3.0","description":"Cryptographically verified XRP payment receipts on the Flare Network. XRPLink uses Flare's Data Connector (FDC) protocol to create on-chain proofs of XRP transactions.","contact":{"url":"https://xrp-link.com"}},"servers":[{"url":"https://xrp-link.com","description":"Production"}],"tags":[{"name":"Attestation","description":"Create and check payment attestations"},{"name":"Public","description":"Public endpoints (no auth required)"},{"name":"Auth","description":"Authentication and account management"},{"name":"Billing","description":"Subscription management"},{"name":"MCP","description":"Model Context Protocol server"}],"paths":{"/api/v1/verify/xrp-payment":{"post":{"tags":["Attestation"],"summary":"Verify an XRP payment","description":"Submit an XRP transaction hash for FDC attestation. Subscription API keys inside quota are not charged extra. Without a key or over quota, the server returns HTTP 402 with x402 payment requirements (XRP or RLUSD on the XRP Ledger). Retry with PAYMENT-SIGNATURE after paying. One payment authorizes exactly one attestation. Proof takes ~90-180 seconds.","security":[{"ApiKeyAuth":[]},{"X402":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["txHash"],"properties":{"txHash":{"type":"string","pattern":"^[0-9A-Fa-f]{64}$","description":"64-character XRP transaction hash"}}},"example":{"txHash":"87AD359A0DB9E27260AAE29766DC858886C54DAC4733D43B1B72CBB90E29B95F"}}}},"responses":{"202":{"description":"Attestation submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResponse"}}}},"400":{"description":"Invalid transaction hash","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key and x402 is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"x402 payment required, payment failed, or subscription quota exceeded (402 body includes paymentRequired when pay-per-use is enabled)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"409":{"description":"x402 payment replay rejected"},"503":{"description":"Price feed unavailable; pay-per-use fails closed"}}}},"/api/v1/status/{id}":{"get":{"tags":["Attestation"],"summary":"Check attestation status","description":"Get the current status and proof data for an attestation by UUID.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Attestation found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"404":{"description":"Attestation not found"}}}},"/api/v1/status-by-tx/{txHash}":{"get":{"tags":["Attestation"],"summary":"Find attestation by transaction hash","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"txHash","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Fa-f]{64}$"}}],"responses":{"200":{"description":"Attestation found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"404":{"description":"Attestation not found"}}}},"/receipt/{txHash}":{"get":{"tags":["Public"],"summary":"View receipt","description":"Get a payment receipt by transaction hash. Returns HTML by default; use Accept: application/json or ?format=json for JSON.","parameters":[{"name":"txHash","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json"]},"description":"Response format"}],"responses":{"200":{"description":"Receipt found","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptResponse"}}}},"404":{"description":"Transaction not found"}}}},"/health":{"get":{"tags":["Public"],"summary":"Health check","responses":{"200":{"description":"Server is healthy"},"503":{"description":"Server is degraded"}}}},"/mcp":{"post":{"tags":["MCP"],"summary":"MCP Streamable HTTP endpoint","description":"Model Context Protocol Streamable HTTP endpoint. initialize, tools/list, and read-only tools work without a key. verify_xrp_payment without payment returns a tool error (HTTP 200) with x402 requirements — never HTTP 403.","parameters":[{"name":"X-API-Key","in":"header","schema":{"type":"string"},"description":"Optional API key for subscription attestations"},{"name":"PAYMENT-SIGNATURE","in":"header","schema":{"type":"string"},"description":"Optional x402 payment payload (base64) for pay-per-use"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"MCP JSON-RPC or SSE response (never 403 for auth)"}}},"get":{"tags":["MCP"],"summary":"MCP SSE stream","description":"Server-sent events stream for MCP notifications.","responses":{"200":{"description":"SSE stream"}}}},"/auth/signup":{"post":{"tags":["Auth"],"summary":"Create account","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8}}}}}},"responses":{"201":{"description":"Account created"},"400":{"description":"Invalid input"}}}},"/auth/login":{"post":{"tags":["Auth"],"summary":"Log in","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"Login successful"},"401":{"description":"Invalid credentials"}}}},"/me":{"get":{"tags":["Auth"],"summary":"Get current user","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"User info"},"401":{"description":"Not authenticated"}}}},"/billing/subscribe":{"post":{"tags":["Billing"],"summary":"Start subscription","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tier"],"properties":{"tier":{"type":"string","enum":["paid","pro"]}}}}}},"responses":{"200":{"description":"Checkout URL returned"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"},"BearerAuth":{"type":"http","scheme":"bearer"},"X402":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 v2 payment payload (base64)"}},"schemas":{"VerifyResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txHash":{"type":"string"},"roundId":{"type":"integer","nullable":true},"status":{"type":"string","enum":["pending","ready","verified","failed","not_found"]}}},"StatusResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txHash":{"type":"string"},"roundId":{"type":"integer","nullable":true},"status":{"type":"string"},"proof":{"type":"object","nullable":true},"verifiedTxHash":{"type":"string","nullable":true},"error":{"type":"string","nullable":true}}},"ReceiptResponse":{"type":"object","properties":{"txHash":{"type":"string"},"status":{"type":"string"},"attestationId":{"type":"string","nullable":true},"roundId":{"type":"integer","nullable":true},"payment":{"type":"object","nullable":true},"proof":{"type":"object","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}},"QuotaError":{"type":"object","properties":{"code":{"type":"string","example":"QUOTA_EXCEEDED"},"message":{"type":"string"},"tier":{"type":"string"},"limit":{"type":"integer"},"used":{"type":"integer"},"resetDate":{"type":"string","format":"date"},"upgradeUrl":{"type":"string"}}},"PaymentRequired":{"type":"object","properties":{"code":{"type":"string","example":"PAYMENT_REQUIRED"},"message":{"type":"string"},"paymentRequired":{"type":"object","description":"x402 v2 PaymentRequired (also in PAYMENT-REQUIRED header, base64)"},"priceUsd":{"type":"number"},"priceXrp":{"type":"number"},"priceRlusd":{"type":"string"}}}}}}