Documentation | xlm402.com

Overview

xlm402 API Documentation

xlm402 provides paid API services over the x402 payment protocol on the Stellar network. Weather, crypto, news, scrape, and collect routes on both networks expose USDC and XLM, with no API keys or subscriptions required.

Weather

Current conditions, forecasts, archives, and historical summaries. Available on mainnet and testnet.

Crypto

Production-grade quotes and candles from official Binance, Kraken, and Coinbase Exchange APIs.

News

Aggregated feeds across 13 categories including tech, ai, global, economics, and more.

Chat

GPT-powered text generation. Mainnet only, requires OPENAI_API_KEY.

Image

Prompt-to-image generation with base64 output. Mainnet only, requires OPENAI_API_KEY.

Scrape

Public-page extraction with robots-aware fetching, metadata, text, markdown, links, and JSON-LD.

Collect

Bounded same-origin collection from a seed URL with regex filtering and dedupe controls.

Getting Started

Quickstart

Call any endpoint with a standard HTTP request. The server responds with 402 Payment Required and payment details. Use a Freighter wallet or x402 client to sign and retry.

Run the server locally

git clone https://github.com/jamesbachini/xlm402
cd xlm402
cp .env.example .env
npm install
npm run dev

Test the API

# Check service health
curl https://xlm402.com/health

# Browse the catalogue
curl https://xlm402.com/api/catalog

# Try a paid endpoint (returns 402)
curl https://xlm402.com/weather/current?latitude=51.5&longitude=-0.1

Configuration

Public settings live in config/app.json. Secrets (OPENAI_API_KEY, wallet keys) go in .env. Chat uses gpt-5.4 and images use gpt-image-1.5.

Payments

x402 Payment Flow

The x402 protocol turns HTTP 402 Payment Required into a native payment flow. No API keys, no subscriptions — just pay per call.

Request

Make a standard HTTP request to any paid route.

402 Response

Server returns payment requirements: price, network, asset, pay-to address, and facilitator URL.

Sign & Retry

Your x402 client signs a Stellar payment and retries with payment headers attached.

Response

The facilitator verifies payment and the server returns the API data.

402 response body

{
  "error": "payment_required",
  "message": "This endpoint requires x402 payment",
  "price_usd": "0.01",
  "assets": [
    { "asset": "USDC", "price": "0.01" }
  ],
  "network": "mainnet",
  "pay_to": "GA4D33Z3EOB6BU4DOXS2JMZK3JQRABN3ERMF3FK5JF5YPG3CEKRI7WM4",
  "facilitator_url": "https://channels.openzeppelin.com/x402",
  "route": "/weather/current"
}

Successful response

{
  "network": "mainnet",
  "paid": true,
  "price_usd": "0.01",
  "assets": ["USDC"],
  "data": { ... }
}

Integration

MCP Integration

To let AI agents (Codex, Claude, etc.) pay for these routes automatically, use the x402-mcp-stellar MCP server. It runs over stdio and exposes wallet info, facilitator checks, and a paid fetch tool.

Setup

Clone and run the MCP server

git clone https://github.com/jamesbachini/x402-mcp-stellar
cd x402-mcp-stellar
cp .env.example .env
npm install
npm run dev

.env configuration

STELLAR_SECRET_KEY=S...
STELLAR_NETWORK=stellar:testnet

# For mainnet:
STELLAR_NETWORK=stellar:pubnet
STELLAR_RPC_URL=https://rpc.lightsail.network/
X402_FACILITATOR_URL=https://channels.openzeppelin.com/x402
X402_FACILITATOR_API_KEY=<your-openzeppelin-api-key>

Register with Codex

Add MCP to Codex

codex mcp add x402-stellar -- \
  npm --silent --prefix /path/to/x402-mcp-stellar run dev

Prerequisites

Node.js 20+, a funded Stellar wallet, this resource server running, and a reachable facilitator. Start with testnet. For mainnet, use the OpenZeppelin relayer with an API key.

Discovery

Discovery Endpoints

Every service publishes structured metadata so AI agents and automation tools can discover, evaluate, and purchase API access programmatically.

/api/catalog

Service definitions, published routes, prices, response types, and network metadata.

/.well-known/x402

x402 manifest with route descriptions and full payment options for discovery clients.

/supported

Facilitator capabilities for mainnet and testnet.

/health

Platform status, route count, networks, and AI enablement.

Formats

Response Format

All successful paid responses share a common JSON envelope.

Parameter	Description
`network`	Network label: mainnet or testnet.
`paid`	Boolean, true on successful paid responses.
`price_usd`	USD price string for the route.
`assets`	Accepted settlement assets for that route and network.
`data`	Endpoint-specific payload.

Error responses

Errors return { "error": "invalid_request", "message": "..." }. Common causes: invalid coordinates, bad date ranges, or malformed body parameters.

API Reference

Weather API

Weather is available on both mainnet and testnet. Forecast and archive routes accept field selection through comma-separated query parameters.

Parameter	Description
`latitude`	Required. Number between -90 and 90.
`longitude`	Required. Number between -180 and 180.
`timezone`	Optional. IANA timezone string or auto.
`forecast_days`	Forecast only. Integer 1-16.
`start_date / end_date`	Archive only. YYYY-MM-DD format, max 366-day span.

Weather Endpoints

Current conditions, forecasts, archives, and historical summaries.

GET /weather/current

mainnet $0.01 USD

Current weather conditions for a latitude and longitude.

Example Query JSON

query.json
{
  "latitude": 51.5072,
  "longitude": -0.1276,
  "timezone": "auto"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/weather/current?latitude=51.5072&longitude=-0.1276&timezone=auto"

Query Parameters

latitude
longitude
timezone=auto

GET /testnet/weather/current

testnet $0.01 USD

Current weather conditions for a latitude and longitude.

Example Query JSON

query.json
{
  "latitude": 51.5072,
  "longitude": -0.1276,
  "timezone": "auto"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/weather/current?latitude=51.5072&longitude=-0.1276&timezone=auto"

Query Parameters

latitude
longitude
timezone=auto

GET /weather/forecast

mainnet $0.01 USD

Forecast weather data with optional daily and hourly field selection.

Example Query JSON

query.json
{
  "latitude": 51.5072,
  "longitude": -0.1276,
  "daily": "temperature_2m_max,temperature_2m_min,precipitation_sum",
  "forecast_days": 5,
  "timezone": "auto"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/weather/forecast?latitude=51.5072&longitude=-0.1276&daily=temperature_2m_max,temperature_2m_min,precipitation_sum&forecast_days=5&timezone=auto"

Query Parameters

latitude
longitude
daily=comma,separated,fields
hourly=comma,separated,fields
forecast_days=1..16
timezone=auto

GET /testnet/weather/forecast

testnet $0.01 USD

Forecast weather data with optional daily and hourly field selection.

Example Query JSON

query.json
{
  "latitude": 51.5072,
  "longitude": -0.1276,
  "daily": "temperature_2m_max,temperature_2m_min,precipitation_sum",
  "forecast_days": 5,
  "timezone": "auto"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/weather/forecast?latitude=51.5072&longitude=-0.1276&daily=temperature_2m_max,temperature_2m_min,precipitation_sum&forecast_days=5&timezone=auto"

Query Parameters

latitude
longitude
daily=comma,separated,fields
hourly=comma,separated,fields
forecast_days=1..16
timezone=auto

GET /weather/archive

mainnet $0.01 USD

Historical archive weather data across a date range.

Example Query JSON

query.json
{
  "latitude": 40.7128,
  "longitude": -74.0060,
  "start_date": "2026-03-01",
  "end_date": "2026-03-07",
  "daily": "temperature_2m_max,temperature_2m_min,precipitation_sum",
  "timezone": "auto"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/weather/archive?latitude=40.7128&longitude=-74.0060&start_date=2026-03-01&end_date=2026-03-07&daily=temperature_2m_max,temperature_2m_min,precipitation_sum&timezone=auto"

Query Parameters

latitude
longitude
start_date=YYYY-MM-DD
end_date=YYYY-MM-DD
daily=comma,separated,fields
hourly=comma,separated,fields
timezone=auto

GET /testnet/weather/archive

testnet $0.01 USD

Historical archive weather data across a date range.

Example Query JSON

query.json
{
  "latitude": 40.7128,
  "longitude": -74.0060,
  "start_date": "2026-03-01",
  "end_date": "2026-03-07",
  "daily": "temperature_2m_max,temperature_2m_min,precipitation_sum",
  "timezone": "auto"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/weather/archive?latitude=40.7128&longitude=-74.0060&start_date=2026-03-01&end_date=2026-03-07&daily=temperature_2m_max,temperature_2m_min,precipitation_sum&timezone=auto"

Query Parameters

latitude
longitude
start_date=YYYY-MM-DD
end_date=YYYY-MM-DD
daily=comma,separated,fields
hourly=comma,separated,fields
timezone=auto

GET /weather/history-summary

mainnet $0.01 USD

Compact summary view over an archive range with hottest, coldest, and precipitation totals.

Example Query JSON

query.json
{
  "latitude": 40.7128,
  "longitude": -74.0060,
  "start_date": "2026-03-01",
  "end_date": "2026-03-07",
  "timezone": "auto"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/weather/history-summary?latitude=40.7128&longitude=-74.0060&start_date=2026-03-01&end_date=2026-03-07&timezone=auto"

Query Parameters

latitude
longitude
start_date=YYYY-MM-DD
end_date=YYYY-MM-DD
timezone=auto

GET /testnet/weather/history-summary

testnet $0.01 USD

Compact summary view over an archive range with hottest, coldest, and precipitation totals.

Example Query JSON

query.json
{
  "latitude": 40.7128,
  "longitude": -74.0060,
  "start_date": "2026-03-01",
  "end_date": "2026-03-07",
  "timezone": "auto"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/weather/history-summary?latitude=40.7128&longitude=-74.0060&start_date=2026-03-01&end_date=2026-03-07&timezone=auto"

Query Parameters

latitude
longitude
start_date=YYYY-MM-DD
end_date=YYYY-MM-DD
timezone=auto

API Reference

News API

News endpoints aggregate multiple RSS and Atom feeds into a normalized response. Available categories: tech, ai, global, economics, blockchain, politics, sports, business, science, entertainment, gaming, security, health.

Parameter	Description
`category`	Path parameter. One of: tech, ai, global, economics, blockchain, politics, sports, business, science, entertainment, gaming, security, health.
`limit`	Optional. Integer 1-30, defaults to 12.
`max_per_feed`	Optional. Integer 1-10, defaults to 6.

News Endpoints

Category-based story aggregation with standardized story objects.

GET /news/tech

mainnet $0.01 USD

Latest technology stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "tech",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/news/tech?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /testnet/news/tech

testnet $0.01 USD

Latest technology stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "tech",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/news/tech?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /news/ai

mainnet $0.01 USD

Latest AI stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "ai",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/news/ai?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /testnet/news/ai

testnet $0.01 USD

Latest AI stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "ai",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/news/ai?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /news/global

mainnet $0.01 USD

Latest global news stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "global",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/news/global?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /testnet/news/global

testnet $0.01 USD

Latest global news stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "global",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/news/global?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /news/economics

mainnet $0.01 USD

Latest economics and markets stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "economics",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/news/economics?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /testnet/news/economics

testnet $0.01 USD

Latest economics and markets stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "economics",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/news/economics?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /news/blockchain

mainnet $0.01 USD

Latest blockchain and crypto stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "blockchain",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/news/blockchain?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /testnet/news/blockchain

testnet $0.01 USD

Latest blockchain and crypto stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "blockchain",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/news/blockchain?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /news/politics

mainnet $0.01 USD

Latest politics stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "politics",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/news/politics?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /testnet/news/politics

testnet $0.01 USD

Latest politics stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "politics",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/news/politics?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /news/sports

mainnet $0.01 USD

Latest sports stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "sports",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/news/sports?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /testnet/news/sports

testnet $0.01 USD

Latest sports stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "sports",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/news/sports?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /news/business

mainnet $0.01 USD

Latest business stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "business",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/news/business?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /testnet/news/business

testnet $0.01 USD

Latest business stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "business",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/news/business?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /news/science

mainnet $0.01 USD

Latest science stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "science",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/news/science?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /testnet/news/science

testnet $0.01 USD

Latest science stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "science",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/news/science?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /news/entertainment

mainnet $0.01 USD

Latest entertainment stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "entertainment",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/news/entertainment?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /testnet/news/entertainment

testnet $0.01 USD

Latest entertainment stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "entertainment",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/news/entertainment?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /news/gaming

mainnet $0.01 USD

Latest gaming stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "gaming",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/news/gaming?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /testnet/news/gaming

testnet $0.01 USD

Latest gaming stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "gaming",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/news/gaming?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /news/security

mainnet $0.01 USD

Latest cybersecurity and security stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "security",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/news/security?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /testnet/news/security

testnet $0.01 USD

Latest cybersecurity and security stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "security",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/news/security?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /news/health

mainnet $0.01 USD

Latest health and medicine stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "health",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/news/health?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

GET /testnet/news/health

testnet $0.01 USD

Latest health and medicine stories mixed from multiple vetted RSS feeds.

Example Query JSON

query.json
{
  "category": "health",
  "limit": 12,
  "max_per_feed": 6
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/news/health?limit=12&max_per_feed=6"

Query Parameters

limit=1..30
max_per_feed=1..10

API Reference

Crypto API

Crypto market data is available on both mainnet and testnet with a normalized request contract. Use source=best to follow the configured fallback order across Binance, Kraken, and Coinbase Exchange.

Parameter	Description
`symbol`	Required. BASE-USD format, for example BTC-USD.
`source`	Optional. best, binance, kraken, or coinbase. Defaults to best.
`interval`	Candles only. One of: 1m, 5m, 15m, 1h, 4h, 1d, 1w, 1M.
`limit`	Candles only. Integer 1-500. Coinbase is capped at 300.
`start / end`	Candles only. Optional ISO-8601 timestamps with start < end.

Crypto Endpoints

Request-time quotes and candles with normalized JSON output and source fallback.

GET /markets/crypto/quote

mainnet $0.01 USD

Normalized crypto quote from Binance, Kraken, or Coinbase Exchange.

Example Query JSON

query.json
{
  "symbol": "BTC-USD",
  "source": "best"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/markets/crypto/quote?symbol=BTC-USD&source=best"

Query Parameters

symbol=BASE-USD
source=best|binance|kraken|coinbase

GET /testnet/markets/crypto/quote

testnet $0.01 USD

Normalized crypto quote from Binance, Kraken, or Coinbase Exchange.

Example Query JSON

query.json
{
  "symbol": "BTC-USD",
  "source": "best"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/markets/crypto/quote?symbol=BTC-USD&source=best"

Query Parameters

symbol=BASE-USD
source=best|binance|kraken|coinbase

GET /markets/crypto/candles

mainnet $0.01 USD

Normalized crypto candles from Binance, Kraken, or Coinbase Exchange.

Example Query JSON

query.json
{
  "symbol": "BTC-USD",
  "interval": "1h",
  "limit": 48,
  "source": "best"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/markets/crypto/candles?symbol=BTC-USD&interval=1h&limit=48&source=best"

Query Parameters

symbol=BASE-USD
interval=1m|5m|15m|1h|4h|1d|1w|1M
source=best|binance|kraken|coinbase
limit=1..500
start=ISO-8601 timestamp
end=ISO-8601 timestamp

GET /testnet/markets/crypto/candles

testnet $0.01 USD

Normalized crypto candles from Binance, Kraken, or Coinbase Exchange.

Example Query JSON

query.json
{
  "symbol": "BTC-USD",
  "interval": "1h",
  "limit": 48,
  "source": "best"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl "https://xlm402.com/testnet/markets/crypto/candles?symbol=BTC-USD&interval=1h&limit=48&source=best"

Query Parameters

symbol=BASE-USD
interval=1m|5m|15m|1h|4h|1d|1w|1M
source=best|binance|kraken|coinbase
limit=1..500
start=ISO-8601 timestamp
end=ISO-8601 timestamp

API Reference

Chat API

Mainnet only. Returns a wrapped GPT Responses API payload with id, model, output_text, status, and usage.

Parameter	Description
`prompt`	Required. String up to 32,000 characters.
`system`	Optional. Instruction string up to 12,000 characters.
`max_output_tokens`	Optional. Integer 64-4096, defaults to 800.
`reasoning_effort`	Optional. One of: none, low, medium, high, xhigh.
`metadata`	Optional. Object of up to 16 string key/value pairs.

Chat Endpoint

Paid text generation against the configured GPT model.

POST /chat/respond

mainnet $0.05 USD

Text inference endpoint for prompts, system instructions, and output controls.

Example Request JSON

request.json
{
  "prompt": "Write a poem about the Stellar network.",
  "system": "Be concise and professional in your response.",
  "reasoning_effort": "medium"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl -X POST "https://xlm402.com/chat/respond" -H "Content-Type: application/json" -d @- <<'JSON'
{
  "prompt": "Write a poem about the Stellar network.",
  "system": "Be concise and professional in your response.",
  "reasoning_effort": "medium"
}
JSON

Body Schema

prompt: string
system?: string
max_output_tokens?: integer 64..4096
reasoning_effort?: none | low | medium | high | xhigh
metadata?: object<string,string>

API Reference

Image API

Mainnet only. Returns base64-encoded image data. Use png or webp output format for transparent backgrounds.

Parameter	Description
`prompt`	Required. Prompt string up to 32,000 characters.
`size`	Optional. auto, 1024x1024, 1536x1024, or 1024x1536.
`quality`	Optional. auto, low, medium, or high.
`background`	Optional. auto, opaque, or transparent.
`output_format`	Optional. jpeg, png, or webp.

Image Endpoint

Prompt-to-image generation with base64 output.

POST /image/generate

mainnet $0.10 USD

Prompt-to-image generation that returns a base64-encoded image payload.

Example Request JSON

request.json
{
  "prompt": "A cinematic satellite view of a storm front above the Atlantic, premium editorial style",
  "size": "1536x1024",
  "quality": "high",
  "output_format": "jpeg"
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl -X POST "https://xlm402.com/image/generate" -H "Content-Type: application/json" -d @- <<'JSON'
{
  "prompt": "A cinematic satellite view of a storm front above the Atlantic, premium editorial style",
  "size": "1536x1024",
  "quality": "high",
  "output_format": "jpeg"
}
JSON

Body Schema

prompt: string
size?: auto | 1024x1024 | 1536x1024 | 1024x1536
quality?: auto | low | medium | high
background?: auto | opaque | transparent
output_format?: jpeg | png | webp
moderation?: auto | low

API Reference

Scrape API

Public HTML extraction on mainnet and testnet. Requests must target public http or https pages and the service respects robots.txt.

Parameter	Description
`url`	Required. Absolute public http or https URL.
`format`	Optional. text or markdown. Defaults to markdown.
`include_links`	Optional. Boolean, defaults to true.
`include_metadata`	Optional. Boolean, defaults to true.
`include_json_ld`	Optional. Boolean, defaults to true.
`max_chars`	Optional. Integer 1000-100000, defaults to 50000.

Scrape Endpoint

Single-URL extraction for public pages.

POST /scrape/extract

mainnet $0.03 USD

Fetch and normalize one public HTML page into structured extraction output.

Example Request JSON

request.json
{
  "url": "https://example.com/article",
  "format": "markdown",
  "include_links": true,
  "include_metadata": true,
  "include_json_ld": true,
  "max_chars": 50000
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl -X POST "https://xlm402.com/scrape/extract" -H "Content-Type: application/json" -d @- <<'JSON'
{
  "url": "https://example.com/article",
  "format": "markdown",
  "include_links": true,
  "include_metadata": true,
  "include_json_ld": true,
  "max_chars": 50000
}
JSON

Body Schema

url: absolute http|https URL
format?: text | markdown
include_links?: boolean
include_metadata?: boolean
include_json_ld?: boolean
max_chars?: integer 1000..100000

POST /testnet/scrape/extract

testnet $0.03 USD

Fetch and normalize one public HTML page into structured extraction output.

Example Request JSON

request.json
{
  "url": "https://example.com/article",
  "format": "markdown",
  "include_links": true,
  "include_metadata": true,
  "include_json_ld": true,
  "max_chars": 50000
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl -X POST "https://xlm402.com/testnet/scrape/extract" -H "Content-Type: application/json" -d @- <<'JSON'
{
  "url": "https://example.com/article",
  "format": "markdown",
  "include_links": true,
  "include_metadata": true,
  "include_json_ld": true,
  "max_chars": 50000
}
JSON

Body Schema

url: absolute http|https URL
format?: text | markdown
include_links?: boolean
include_metadata?: boolean
include_json_ld?: boolean
max_chars?: integer 1000..100000

API Reference

Collect API

Synchronous same-origin collection for small public datasets. Use include and exclude regex filters to bound the crawl and choose canonical or final-URL dedupe.

Parameter	Description
`seed_url`	Required. Absolute public http or https URL.
`scope`	Optional. same_origin only in v1.
`max_pages`	Optional. Integer 1-10, defaults to 10.
`max_depth`	Optional. Integer 0-2, defaults to 2.
`include_patterns / exclude_patterns`	Optional. Arrays of regex strings matched against path and query.
`dedupe`	Optional. canonical_url or final_url. Defaults to canonical_url.
`max_chars_per_page`	Optional. Integer 1000-50000, defaults to 30000.

Collect Endpoint

Small bounded collection runs from one seed URL.

POST /collect/run

mainnet $0.08 USD

Run a bounded same-origin collection starting from one public seed URL.

Example Request JSON

request.json
{
  "seed_url": "https://example.com/blog",
  "scope": "same_origin",
  "max_pages": 5,
  "max_depth": 1,
  "include_patterns": ["/blog/"],
  "exclude_patterns": ["/tag/"],
  "format": "markdown",
  "dedupe": "canonical_url",
  "max_chars_per_page": 30000
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl -X POST "https://xlm402.com/collect/run" -H "Content-Type: application/json" -d @- <<'JSON'
{
  "seed_url": "https://example.com/blog",
  "scope": "same_origin",
  "max_pages": 5,
  "max_depth": 1,
  "include_patterns": ["/blog/"],
  "exclude_patterns": ["/tag/"],
  "format": "markdown",
  "dedupe": "canonical_url",
  "max_chars_per_page": 30000
}
JSON

Body Schema

seed_url: absolute http|https URL
scope?: same_origin
max_pages?: integer 1..10
max_depth?: integer 0..2
include_patterns?: string[]
exclude_patterns?: string[]
format?: text | markdown
dedupe?: canonical_url | final_url
max_chars_per_page?: integer 1000..50000

POST /testnet/collect/run

testnet $0.08 USD

Run a bounded same-origin collection starting from one public seed URL.

Example Request JSON

request.json
{
  "seed_url": "https://example.com/blog",
  "scope": "same_origin",
  "max_pages": 5,
  "max_depth": 1,
  "include_patterns": ["/blog/"],
  "exclude_patterns": ["/tag/"],
  "format": "markdown",
  "dedupe": "canonical_url",
  "max_chars_per_page": 30000
}

Edit this JSON before trying the endpoint. The paid retry uses the exact same payload.

CLI Example

curl

curl -X POST "https://xlm402.com/testnet/collect/run" -H "Content-Type: application/json" -d @- <<'JSON'
{
  "seed_url": "https://example.com/blog",
  "scope": "same_origin",
  "max_pages": 5,
  "max_depth": 1,
  "include_patterns": ["/blog/"],
  "exclude_patterns": ["/tag/"],
  "format": "markdown",
  "dedupe": "canonical_url",
  "max_chars_per_page": 30000
}
JSON

Body Schema

seed_url: absolute http|https URL
scope?: same_origin
max_pages?: integer 1..10
max_depth?: integer 0..2
include_patterns?: string[]
exclude_patterns?: string[]
format?: text | markdown
dedupe?: canonical_url | final_url
max_chars_per_page?: integer 1000..50000