--- name: lumi-api description: Pay-per-call crypto market reads from Lumi Trades (daily market brief, signals, support/resistance levels, paper-trade ideas + track record, BTC + macro backdrop, yen carry-trade watch, Fear & Greed sentiment, events calendar) for 13 coins, paid in XRP or RLUSD or USDC on the XRP Ledger, or USDC on Base via x402. Use when you need a current technical read or trade-idea context for HBAR, XLM, XRP, ZBCN, AXL, XDC, BTC, ETH, SOL, DOGE, ADA, LINK, SUI. --- # Lumi API (agent guide) Base URL: https://api.lumitrades.io Network: `xrpl:0` (mainnet). Assets: XRP or RLUSD (Ripple USD, issuer `rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De`, currency `524C555344000000000000000000000000000000`) or USDC (Circle USDC, issuer `rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE`, currency `5553444300000000000000000000000000000000`). Pay to: `rM8kmmnz5qPMg7V3r7SHYXgDGvm8PhzLvM`. Also: `eip155:8453` (Base). Asset: USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`. Pay to: `0x5E617bac19912e6d212CB303ae84655E9E203532`. Facilitator: https://facilitator.payai.network. Protocol: [x402](https://xrpl.org/docs/agents/agentic-payments-x402) v2, `exact` scheme (one presigned XRPL Payment per call, or one EIP-3009 USDC authorization on Base). No API key, no account, no sign-up. A2A agent card: https://api.lumitrades.io/.well-known/agent-card.json. MCP: https://api.lumitrades.io/mcp. ## What you can buy | Endpoint | Price | What you get | |---|---|---| | `GET /v1/signal/{coin}` | 0.005 XRP (5000 drops) or 0.01 RLUSD or 0.01 USDC or 0.01 USDC on Base | Mechanical buy/sell read for one coin: overall label + score, per-timeframe (1h/4h/1d) labels and an indicator summary (RSI, MACD, EMA stack, Bollinger, StochRSI, volume). | | `GET /v1/levels/{coin}` | 0.005 XRP (5000 drops) or 0.01 RLUSD or 0.01 USDC or 0.01 USDC on Base | Lumi's support/resistance levels, bias, 7-day bull/base/bear projection, commentary, catalysts and cited sources for one coin. | | `GET /v1/slate` | 0.01 XRP (10000 drops) or 0.02 RLUSD or 0.02 USDC or 0.02 USDC on Base | Current paper-trade ideas: direction, entry/entry zone, stop, targets, leverage, conviction, status, plus 'no setup' notes and the public track record. | | `GET /v1/market` | 0.01 XRP (10000 drops) or 0.02 RLUSD or 0.02 USDC or 0.02 USDC on Base | Market backdrop: BTC levels/projection/signal, macro (yen/USDJPY note, total cap, dominance, fear & greed, BTC perp funding/OI) and breadth across Lumi's 13 coins. | | `GET /v1/brief` | 0.02 XRP (20000 drops) or 0.03 RLUSD or 0.03 USDC or 0.03 USDC on Base | Today's market brief, the same read as Lumi's newsletter and Shorts: BTC price/levels/signal, CoinMarketCap Fear & Greed, funding, top/bottom movers, key levels for 13 coins, yen watch, events in the next 48h, paper trades + record, sourced news. JSON with a ready-to-use `markdown` field; add ?format=md (or Accept: text/markdown) for text/markdown. | | `GET /v1/macro/yen` | 0.01 XRP (10000 drops) or 0.015 RLUSD or 0.015 USDC or 0.015 USDC on Base | Yen carry-trade watch: USD/JPY and Nikkei 225 (price, 1d/5d change, ranges), a rule-based carry-trade risk level (low/watch/elevated) around the 155 USD/JPY line with reasons, Lumi's yen note, BTC context, upcoming Japan events (BOJ, CPI) and sources. | | `GET /v1/sentiment` | 0.005 XRP (5000 drops) or 0.01 RLUSD or 0.01 USDC or 0.01 USDC on Base | Crypto sentiment snapshot: CoinMarketCap Fear & Greed (value, band, day-over-day change), BTC perp funding rate with a plain-English read + open interest (OKX), total market cap/volume/dominance, and breadth/signal-label counts across Lumi's 13 coins. | | `GET /v1/events` | 0.005 XRP (5000 drops) or 0.01 RLUSD or 0.01 USDC or 0.01 USDC on Base | Upcoming macro and crypto events that can move prices: timed releases/decisions (UTC + US Central, with why it matters) and dated per-coin catalysts (Fed, BOJ, CPI, network upgrades, conferences). Every row is sourced. | | `GET /v1/trades` | 0.01 XRP (10000 drops) or 0.02 RLUSD or 0.02 USDC or 0.02 USDC on Base | Lumi's full paper-trade history (every idea: entry, stop, targets, leverage, outcome, reasoning) and an honest computed track record: win rate, sum/avg P&L, best/worst, by coin, by direction, equity curve, open unrealized P&L. | `{coin}` is a ticker or CoinGecko id, case-insensitive: HBAR, XLM, XRP, ZBCN, AXL, XDC, BTC, ETH, SOL, DOGE, ADA, LINK, SUI. Unknown coins return 404 **before** any payment is requested. Which one to call: - Need "what's going on in crypto today" in one call? `GET /v1/brief` (add `?format=md` for ready-to-post markdown). - Macro risk from Japan / the yen carry trade? `GET /v1/macro/yen`. - Mood/positioning only? `GET /v1/sentiment`. What's scheduled? `GET /v1/events`. - Is Lumi any good? `GET /v1/trades` (every paper trade, wins and losses). Current ideas only? `GET /v1/slate`. - One coin? `GET /v1/signal/{coin}` + `GET /v1/levels/{coin}`. Fields that are not available at request time are omitted, never filled with guesses. **You only pay when you get data.** Before a price is even quoted, the API loads and checks every input the endpoint needs (present, non-empty, recently refreshed). If anything is missing, empty or stale you get `503` with `"note": "Not charged."` and **no 402 quote**, so no payment can be signed or settled. The response body is built *before* the payment is settled and is served right after a validated `tesSUCCESS`: a settled payment always returns the data you paid for. Free: `GET /`, `GET /health`, `GET /skill.md`, `GET /v1/coins`, `GET /.well-known/x402`, `GET /.well-known/agent-card.json`, `GET /openapi.json`, `POST /mcp`, `POST /a2a`. Every paid response is JSON with `timestamp`, `source: "lumitrades.io"`, a `payment` block (network, tx hash, explorer link) and a `disclaimer`. Data is refreshed from lumitrades.io roughly every minute; analysis text is updated a few times a day. ## How payment works 1. `GET https://api.lumitrades.io/v1/signal/XRP` with no payment -> **HTTP 402**. The body (and the base64 `PAYMENT-REQUIRED` header) is an x402 v2 `PaymentRequired`: `accepts[0] = { scheme: "exact", network: "xrpl:0", asset: "XRP", amount: "", payTo: "rM8kmmnz5qPMg7V3r7SHYXgDGvm8PhzLvM", maxTimeoutSeconds: 300, extra: { invoiceId, sourceTag: 804681468 } }` `accepts[1]` is the same quote in **RLUSD** (Ripple USD): `{ asset: "524C555344000000000000000000000000000000", amount: "", extra: { issuer: "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De", invoiceId, sourceTag, symbol: "RLUSD" } }`. `accepts[2]` is the same quote in **USDC** (Circle USDC): `{ asset: "5553444300000000000000000000000000000000", amount: "", extra: { issuer: "rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE", invoiceId, sourceTag, symbol: "USDC" } }`. Pick one option and echo it back unchanged as `accepted` (all options share one invoice; it can be paid once). To pay in a stablecoin your wallet needs a trust line to that issuer and a balance; the Payment's `Amount` is `{ currency, issuer, value }` and `SendMax` equals `Amount` (no conversion). 2. Sign (do not submit) an XRPL `Payment` for exactly `amount` drops to `payTo`, with `SourceTag`, a `LastLedgerSequence`, and the invoice bound via a Memo (`MemoData = hex(utf8(invoiceId))`) and/or `InvoiceID = SHA-256(invoiceId)`. 3. Retry the same request with header `PAYMENT-SIGNATURE: base64(JSON{ x402Version: 2, accepted: , payload: { signedTxBlob, invoiceId } })`. 4. The server has the facilitator (https://xrpl-facilitator-mainnet.t54.ai) verify and submit your payment. On a validated `tesSUCCESS` you get **200** with the data and a `PAYMENT-RESPONSE` header: base64 `{ success, transaction, network, payer }`. Quotes expire after 300s and each invoice can be paid once. If you get 402 again, read `error` and pay the fresh quote. 503 with `retryable: true, settlementAttempted: false` is safe to retry with the same header. 409 `settlement_status_unknown`: look up your tx on the ledger before paying again. The x402-xrpl SDKs (T54, the reference XRPL implementation) do all of this for you. ### Paying with USDC on Base instead The same 402 also lists `accepts[3]` = `{ scheme: "exact", network: "eip155:8453", asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", amount: "", payTo: "0x5E617bac19912e6d212CB303ae84655E9E203532", maxTimeoutSeconds: 300, extra: { name: "USD Coin", version: "2", invoiceId, symbol: "USDC", decimals: 6 } }`. Sign an EIP-3009 `transferWithAuthorization` for exactly `amount` to `payTo` and retry with `PAYMENT-SIGNATURE: base64(JSON{ x402Version: 2, accepted: , payload: { signature, authorization: { from, to, value, validAfter, validBefore, nonce } } })`. Lumi's facilitator (https://facilitator.payai.network) verifies it and submits it on Base, paying the gas: your wallet needs USDC only, no ETH. Same rules: one invoice, one payment, never charged when data is stale. The official x402 client packages (`@x402/fetch` + `@x402/evm`) do this for you and skip the XRPL options automatically. ## Example: TypeScript / Node (npm `x402-xrpl`) ```ts import { Wallet } from "xrpl"; import { x402Fetch, decodePaymentResponseHeader } from "x402-xrpl"; const fetchPaid = x402Fetch({ wallet: Wallet.fromSeed(process.env.XRPL_SEED!), // your agent's wallet network: "xrpl:0", wsUrl: "wss://xrplcluster.com", maxValue: "20000", // spend cap per call, in drops }); const res = await fetchPaid("https://api.lumitrades.io/v1/signal/XRP"); console.log(res.status, await res.json()); const receipt = res.headers.get("PAYMENT-RESPONSE"); if (receipt) console.log(decodePaymentResponseHeader(receipt)); // { success, transaction, ... } ``` Pay in a stablecoin instead (wallet must hold it on a trust line to the issuer): ```ts const STABLE = { RLUSD: { currency: "524C555344000000000000000000000000000000", issuer: "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De" }, USDC: { currency: "5553444300000000000000000000000000000000", issuer: "rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE" } }; const want = STABLE.RLUSD; const fetchStable = x402Fetch({ wallet: Wallet.fromSeed(process.env.XRPL_SEED!), network: "xrpl:0", wsUrl: "wss://xrplcluster.com", // pick the stablecoin option and cap it at 0.05 per call paymentRequirementsSelector: (accepts) => { const r = accepts.find((a: any) => a.asset === want.currency && a.extra?.issuer === want.issuer); if (!r || Number(r.amount) > 0.05) throw new Error("no acceptable stablecoin quote"); return r; }, }); ``` Note: the SDK's numeric `maxValue` compares raw `amount` strings across assets (drops for XRP, a decimal value for stablecoins), so use a selector like the one above when paying in a stablecoin. ## Example: USDC on Base (npm `@x402/fetch`, `@x402/evm`, `viem`) ```ts import { wrapFetchWithPayment, x402Client, decodePaymentResponseHeader } from "@x402/fetch"; import { registerExactEvmScheme } from "@x402/evm/exact/client"; import { privateKeyToAccount } from "viem/accounts"; const client = new x402Client(); registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`) }); const fetchPaid = wrapFetchWithPayment(fetch, client); // picks the eip155:8453 USDC option const res = await fetchPaid("https://api.lumitrades.io/v1/brief"); console.log(res.status, await res.json()); console.log(decodePaymentResponseHeader(res.headers.get("PAYMENT-RESPONSE")!)); // { success, transaction, network, payer } ``` ## Example: Python (PyPI `x402-xrpl`) ```python import os from xrpl.wallet import Wallet from x402_xrpl.clients import x402_requests, decode_payment_response session = x402_requests( Wallet.from_seed(os.environ["XRPL_SEED"]), rpc_url="https://xrplcluster.com/", network_filter="xrpl:0", scheme_filter="exact", ) r = session.get("https://api.lumitrades.io/v1/market", timeout=180) print(r.status_code, r.json()["macro"]["yen_note"]) print(decode_payment_response(r.headers["PAYMENT-RESPONSE"])) ``` ## MCP - **Remote MCP server:** `https://api.lumitrades.io/mcp` (Streamable HTTP, stateless; protocol 2026-07-28 and 2025-03-26 .. 2025-11-25). Add it as a remote MCP connector URL. Free tools: `lumi_catalog`, `lumi_coins`, `lumi_quote`. Paid tools (`lumi_brief`, `lumi_signal`, `lumi_levels`, `lumi_slate`, `lumi_market`, `lumi_macro_yen`, `lumi_sentiment`, `lumi_events`, `lumi_trades`) return the price and how to pay, since a remote connector has no wallet. - **Local MCP server that pays for you:** `npx -y lumi-trades-mcp` with `XRPL_SEED` set (npm `lumi-trades-mcp`, MCP Registry `io.github.cypher-osiris/lumi-trades-mcp`). Same tools; each paid call is an x402 payment from your wallet within per-call caps and a session budget. ## A2A - **Agent card:** `https://api.lumitrades.io/.well-known/agent-card.json` (alias `/.well-known/agent.json`), A2A protocol 1.0 with 0.3 compatibility fields. - **JSON-RPC endpoint:** `POST https://api.lumitrades.io/a2a` with `SendMessage` (A2A 1.0) or `message/send` (0.3). Send text such as "list coins", "catalog" or "signal XRP", or a data part `{ "skill": "signal", "coin": "XRP" }`. Free skills (`catalog`, `coins`, `quote`) answer inline. Paid skills answer with the live x402 terms (every network option) and the REST URL to pay at; nothing is charged over A2A. ## Rules of use - Analytics and education only. Not financial advice. Trade ideas are paper trades tracked publicly on lumitrades.io, not orders or signals to copy. Crypto is volatile and leverage can magnify losses. Do your own research. - Trade ideas are a public paper-trading slate. Do not present them as personalised advice. - Cite "Lumi Trades (lumitrades.io)" when you surface this data to people.