← Back to Home

Developers

Integrate AI agents with 90-country economic data via x402 micropayments on the XRP Ledger or Solana USDC.

Quick Start

1. Send a request

# Standard — 1 XRP (XRPL)
POST https://xrplme.online/wc/v1/{country}/bot
Content-Type: application/json

{"message": "Tourism numbers for Thailand Q2 2025", "session_id": "demo-001"}

# Standard — 1 USDC (Solana)
POST https://xrplme.online/wc/v1/{country}/bot-solana
Content-Type: application/json

{"message": "Tourism numbers for Thailand Q2 2025", "session_id": "demo-001"}

2. Receive 402 Payment Required

HTTP/1.1 402 Payment Required
X-INV-ID:          <invoice_hash>
X-PAYMENT-ADDRESS: r...<pay_to_address>
X-AMOUNT:          1000000  (drops, = 1 XRP)
X-DEST-TAG:        <dest_tag>

2b. Solana 402 Response (bot-solana endpoints)

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "accepts": [
    {
      "payTo": "5KMiN7...",
      "amount": 1000000,
      "asset": "EPjFW...",
      "network": "solana"
    }
  ]
}
Tip: Solana USDC endpoints return payTo, amount (raw, 6 decimals = 1 USDC), and qrData (Solana Pay URI). See the Solana payment example for the full flow.

3. Pay & retry

Pay in XRP via Xaman or Joey wallet, or sign programmatically with the xrpl SDK. Pay in USDC via any Solana Pay wallet (Xaman, Phantom, Solflare). Retry your original request with the payment signature header. No API keys needed.

3b. Retry headers

# After paying, retry the same POST with:
X-PAYMENT-SIGNATURE: <tx_hash>        # XRPL: signed transaction hash
X-INVOICE-ID:          <invoice_hash>  # matches the 402 invoiceId

# For Solana USDC, use the x_sol_payload header instead:
x_sol_payload: <base64_payment_payload>

3c. Base (USDC) Payments

Same country data, same three tiers, same request body and response shape as the XRPL and Solana routes, payable in USDC on Base.

POST https://xrplme.online/wc/v1/{country}/bot-evm          $1.00 USDC
POST https://xrplme.online/wc/v1/{country}/bot-evm/ai       $7.00 USDC
POST https://xrplme.online/wc/v1/{country}/bot-evm/custom  $15.00 USDC

The 402 challenge

HTTP/1.1 402 Payment Required
{
  "x402Version": 2,
  "resource": { "url": "https://xrplme.online/wc/v1/thailand/bot-evm", ... },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "1000000",
    "payTo": "0xa9FA5f8b14A8f683Ca634f34f0d3f5688417438c",
    "maxTimeoutSeconds": 600,
    "extra": { "settlement": "onchain-transfer", "decimals": 6 }
  }]
}

Paying

  1. Send at least the tier amount in USDC on Base to the payTo address above.
  2. Copy the transaction hash from your wallet or a Base explorer.
  3. Retry the same POST with that hash in the payment header.
curl -X POST https://xrplme.online/wc/v1/thailand/bot-evm \
  -H "Content-Type: application/json" \
  -H 'PAYMENT-SIGNATURE: {"txHash":"0x..."}' \
  -d '{"message":"recent policy changes"}'

A 200 returns the records. One transfer buys one call: a reused hash returns 409, a transfer below the tier price or older than one hour is rejected with 402, and a payment made on another chain or sent to another address is not accepted. The transfer is verified directly against Base, so nothing sits between your payment and the data.

Building against it

A Base Sepolia twin runs the identical verification so you can rehearse without real money: POST /wc/v1/{country}/bot-evm-test[/ai|/custom] on eip155:84532, same prices in test USDC. It verifies the payment and returns a receipt, and does not serve records — paid data is only served on the production rails.


MCP tools

11 tools. Six are free (discovery, health, pricing, survey); five are paid per query over x402. Paid tools take the payment headers shown in the examples below.

ToolWhat it returnsAccessPrice
xrplme_list_countriesList all 90 countries with slug, name, live statusFree—
xrplme_get_country_statusLive health probe: record count and last-refresh dateFree—
xrplme_get_pricingPricing on all three railsFree—
xrplme_get_country_dataSource-backed economic, policy and regulatory dataPaid1 XRP or $1.00 USDC
xrplme_get_country_schemaStructured record plus freshnessPaid1 XRP or $1.00 USDC
xrplme_screenSanctions / screening check for a person or companyPaid$2.00 USDC
xrplme_entity_lookupCompany look-up and permanent entity IDPaid$1.00 USDC
xrplme_entity_ownershipOwnership chain to the ultimate parentPaid$5.00 USDC
xrplme_get_survey_questionsSurvey questions for agentsFree—
xrplme_submit_surveySubmit agent feedbackFree—
xrplme_get_survey_statsAggregated survey statisticsFree—

MCP Integration (AI Agents)

# Initialize MCP session
POST https://api.xrplme.online/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "agent", "version": "1.0" }
  }
}

Copy-paste client config

# Python (mcp SDK)
from mcp import ClientSession, StdioServerParameters
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client("https://api.xrplme.online/mcp") as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("xrplme_list_countries", {})
        print(result)

# Node.js (@modelcontextprotocol/sdk)
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api.xrplme.online/mcp")
);
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);
const result = await client.callTool({ name: "xrplme_list_countries", arguments: {} });
console.log(result);

Endpoints

EndpointCost (XRPL)Cost (Solana)Description
GET /wc/v1/{country}/healthFREEFREECheck country availability
POST /wc/v1/{country}/bot1 XRP1 USDCStandard tier — factual data
POST /wc/v1/{country}/bot/ai5 XRP7 USDCAI-enhanced analysis (deep synthesis)
POST /wc/v1/{country}/bot-solana1 XRP1 USDCFactual data (Solana USDC)
POST /wc/v1/{country}/bot-solana/ai5 XRP7 USDCAI-enhanced analysis (Solana USDC)
POST /mcpx402 / toolx402 / toolMCP protocol (AI agents)

Countries (90)

All 90 countries are listed with their exact endpoints and prices on the countries page. Slugs are long names: thailand, hong_kong, papua-new-guinea.

No USDC? Fund your wallet with a card

The rails accept XRP on the XRP Ledger or USDC on Solana. If you hold neither, buy USDC with a debit or credit card at Crossmint — Apple Pay and Google Pay work — with your own Solana wallet as the destination, then pay the endpoint from that wallet.

Three things worth knowing:

All 90 countries, endpoints and prices are listed on the countries page.

SDKs & Examples

Response Schema (v1)

All paid API responses (REST + MCP) follow the v1 JSON schema at schema/v1/response-schema.json. Key fields:

Example after successful payment:

{
  "meta": {
    "country_slug": "thailand",
    "query_id": "q_thailand_...",
    "retrieved_at": "2026-10-23T12:00:00Z",
    "payment": {"rail": "xrpl", "txid": "E5A...", "amount": "1 XRP", "invoice_id": "..."},
    "schema_version": "1.0.0"
  },
  "sources": [...],
  "facts": {...},
  "synthesis": {...},
  "agent_hints": {...}
}

New datasets: screening and company look-up

Two more datasets on the same rails. Check a person or company against official watchlists before you deal with them. Look up a company and walk its ownership to the ultimate parent. Pay per call in XRP or USDC, no signup, no key.

Screening
$2.00 / check
/wc/screen/bot · /bot-solana · /bot-evm
Company look-up
$1.00 / lookup
/wc/entity/lookup/bot · /bot-solana · /bot-evm
Ownership tree
$5.00 / tree
/wc/entity/ownership/bot · /bot-solana · /bot-evm
curl -X POST https://xrplme.online/wc/screen/bot-evm \ -H "Content-Type: application/json" \ -d '{"name":"Smith Holdings Ltd"}'