XRPLink API Documentation

Generate cryptographically verified receipts for XRP payments on the Flare Network.

Contents Authentication Receipts Attestation Billing MCP Server Errors

Authentication

XRPLink uses API keys for the attestation API and JWT bearer tokens for account and billing endpoints. Create an account to get a free API key.

Create an account

POST/auth/signuppublic

Creates a user and returns a session token plus a free-tier API key.

curl -X POST https://xrp-link.com/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"yourpassword"}'

// Response
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "apiKey": "sk_live_..."
}

Log in

POST/auth/loginpublic

Returns a session token and your API key.

curl -X POST https://xrp-link.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"yourpassword"}'

Current user

GET/mebearer token

Returns your user info, plan tier, and API keys.

curl https://xrp-link.com/me \
  -H "Authorization: Bearer <your-token>"

Receipts

View a receipt

GET/receipt/:txHashpublic

Returns an HTML receipt page for any XRP transaction. No API key required. If the transaction is already attested, the full cryptographic receipt is shown; otherwise the XRP Ledger data is displayed with instructions to attest.

curl https://xrp-link.com/receipt/87AD359A0DB9E27260AAE29766DC858886C54DAC4733D43B1B72CBB90E29B95F

Attestation

Attesting a payment generates the on-chain cryptographic proof. Use a subscription API key (inside monthly quota) or pay per attestation with x402 on the XRP Ledger (XRP or RLUSD). Proofs are ready in ~90-180 seconds (FDC voting round). Status lookups stay free.

Verify an XRP payment

POST/api/v1/verify/xrp-paymentAPI key or x402

Submits a transaction hash for attestation. Subscribers inside quota skip payment. Otherwise the server returns HTTP 402 with x402 requirements; retry with PAYMENT-SIGNATURE after paying. One payment = one attestation.

curl -X POST https://xrp-link.com/api/v1/verify/xrp-payment \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_..." \
  -d '{"txHash":"87AD359A0DB9E27260AAE29766DC858886C54DAC4733D43B1B72CBB90E29B95F"}'

// Response (HTTP 202)
{
  "id": "3f0c8e2a-...",
  "txHash": "87AD359A0DB9E27260AAE29766DC858886C54DAC4733D43B1B72CBB90E29B95F",
  "roundId": 1393372,
  "status": "pending"
}

Check attestation status

GET/api/v1/status/:idAPI key

Check the status of an attestation by UUID.

curl https://xrp-link.com/api/v1/status/3f0c8e2a-... \
  -H "X-API-Key: sk_live_..."

// Statuses: pending, ready, verified, failed, not_found

Look up by transaction

GET/api/v1/status-by-tx/:txHashAPI key

Find an attestation by the original XRP transaction hash.

Register a webhook

POST/api/v1/webhooksAPI key

curl -X POST https://xrp-link.com/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_..." \
  -d '{"url":"https://your-app.com/hooks/xrp"}'

Billing

POST/billing/subscribebearer token

Create a Stripe Checkout session for a plan. Returns a redirect URL.

curl -X POST https://xrp-link.com/billing/subscribe \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{"tier":"paid"}'

// Response
{ "url": "https://checkout.stripe.com/c/pay/..." }

GET/billing/portalbearer token

Get a link to manage or cancel your subscription.

MCP Server

XRPLink exposes an MCP server so AI agents can verify payments directly. Connect via stdio (local) or Streamable HTTP (remote).

Remote HTTP Endpoint

POST/mcpkeyless discovery

Streamable HTTP. initialize, tools/list, and read-only tools work without a key (no HTTP 403). verify_xrp_payment accepts X-API-Key or x402 PAYMENT-SIGNATURE; unpaid calls return a tool error with payment requirements.

Tool	Auth	Description
`verify_xrp_payment`	API key or x402	Submit a txHash for attestation (subscription quota or one x402 payment)
`get_attestation_status`	keyless	Check attestation by UUID
`lookup_attestation_by_tx`	keyless	Find attestation by txHash
`get_attestation_by_round`	keyless	List attestations by round ID
`get_server_info`	keyless	Server, network, and contract info

# Initialize MCP session and list tools
curl -X POST https://xrp-link.com/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_..." \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

# stdio transport (local agents using operator's wallet)
npm run start:mcp

Agent Discovery

For automated discovery, XRPLink provides:

/llms.txt — Agent-oriented summary
/openapi.json — OpenAPI 3.0 spec
/.well-known/mcp.json — MCP server metadata

Errors

Errors are returned as JSON with a machine-readable code and a human-readable message:

{
  "error": "INVALID_TX_HASH",
  "message": "Expected 64 hex characters for transaction hash",
  "suggestedAction": "Provide a valid XRP transaction hash..."
}

Code	HTTP	Meaning
`MISSING_API_KEY`	401	X-API-Key header missing and x402 not configured
`INVALID_API_KEY`	401	API key invalid and x402 not configured
`PAYMENT_REQUIRED`	402	x402 quote: pay XRP or RLUSD for one attestation
`QUOTA_EXCEEDED`	402	Monthly attestation limit reached (includes x402 quote when pay-per-use is enabled)
`PAYMENT_REPLAY`	409	That x402 payment was already used
`PRICE_UNAVAILABLE`	503	FTSO price feed down; pay-per-use fails closed
`RATE_LIMITED`	429	Per-minute limit exceeded for your tier
`INVALID_TX_HASH`	400	Not a valid 64-hex transaction hash
`SUBMIT_FAILED`	500	Attestation submission to FdcHub failed
`NOT_FOUND`	404	Resource not found
`FORBIDDEN`	403	Requires a higher plan tier
`AUTH_FAILED`	401	Invalid email/password
`MISSING_AUTH`	401	Bearer token missing
`INVALID_AUTH`	401	Bearer token invalid or expired