API Reference Overview

Base URL: https://api.foursec.xyz

All paid endpoints require payment via x402 (Base USDC) or MPP (Tempo USDC). See Authentication and Payment.

Endpoints

DEX Endpoints

Method	Path	Cost	Description
GET	/price/:symbol	$0.01	Real-time aggregated price from 8+ DEXes
GET	/price/history/:symbol	$0.02	Historical OHLCV candlestick data
GET	/volume/:symbol	$0.02	24h trading volume across all DEXes
GET	/spread/:pair	$0.02	Bid/ask spread analysis
GET	/arbitrage-opportunity	$0.05	Cross-DEX arbitrage scanner
GET	/volatility-index/:symbol	$0.03	Risk metrics: VaR, Sharpe, volatility
POST	/price-alert	$0.04	Create webhook price alert
POST	/price-alert/:id/extend	$0.02	Extend price alert duration

Funding Rate Endpoints

Method	Path	Cost	Description
GET	/funding-rate/:symbol	$0.02	Current perpetual funding rate with signal
GET	/funding-rate/history/:symbol	$0.03	Historical funding rate data
GET	/funding-rate/extreme	$0.02	Extreme funding rates scanner across markets

Liquidation Endpoints

Method	Path	Cost	Description
GET	/liquidation/heatmap/:symbol	$0.05	Liquidation heatmap with cascade risk levels
GET	/liquidation/recent	$0.03	Recent liquidations with long/short breakdown
POST	/liquidation/alert	$0.06	Create liquidation cascade alert webhook
POST	/liquidation/alert/:id/extend	$0.03	Extend liquidation alert duration

Futures Analytics

Method	Path	Cost	Description
GET	/futures/funding-compare/:symbol	$0.03	Cross-exchange funding rate comparison
GET	/futures/open-interest/:symbol	$0.03	Aggregated open interest (Binance, OKX, Bybit)
GET	/futures/long-short/:symbol	$0.02	Top traders long/short ratio
GET	/futures/basis/:symbol	$0.02	Spot vs perpetual basis (carry-trade signal)
GET	/futures/predicted-funding/:symbol	$0.02	Predicted next funding rate

CEX Market Data (v1)

Method	Path	Cost	Description
GET	/api/v1/prices	$0.005	Batch CEX prices via CCXT multi-exchange (e.g. ?symbols=btc,eth,sol)
GET	/api/v1/market/:id	$0.005	Market details by CoinGecko ID (e.g. bitcoin)
GET	/api/v1/market/:id/history	$0.01	Historical market data from CEX sources

Free Endpoints

Method	Path	Description
GET	/health	Health check
GET	/api/v1/status	Detailed system status
GET	/price-alert/:id	Check price alert status by ID
DELETE	/price-alert/:id	Cancel a price alert
GET	/price-alerts	List all active price alerts
GET	/liquidation/alerts	List all active liquidation alerts
GET	/liquidation/alert/:id	Check liquidation alert status
DELETE	/liquidation/alert/:id	Cancel a liquidation alert
GET	/	API info and endpoint list
GET	/openapi.json	OpenAPI specification
GET	/.well-known/x402.json	x402 payment discovery
GET	/.well-known/mcp.json	MCP server manifest
POST	/mcp	MCP JSON-RPC 2.0 endpoint
GET	/agent.json	AI agent card
GET	/llms.txt	LLM-readable documentation
GET	/metrics	API transaction metrics

Supported Symbols

DEX Symbols (EVM tokens)

Any token actively traded on supported DEXes. Common examples: ETH, BTC, SOL, LINK, UNI, AAVE, ARB, PEPE, USDC.

Symbols are uppercase for DEX endpoints.

CEX Symbols

Use lowercase CoinGecko IDs for /api/v1/market/:id (e.g. bitcoin, ethereum, solana).

Use comma-separated symbols for /api/v1/prices?symbols=btc,eth,sol.

Response Format

All responses are JSON:

{
  "success": true,
  "data": {
    "symbol": "ETH",
    "price_usd": 1743.34,
    "price_change_24h": -0.837,
    "volume_24h_usd": 187882.21,
    "liquidity_usd": 45000000,
    "dex_count": 3,
    "sources": {
      "uniswap_v3": 1743.30,
      "sushiswap": 1743.38
    },
    "last_updated": "2026-07-08T12:09:30Z"
  }
}

Error responses:

{
  "error": "symbol_not_found",
  "message": "No DEX price data for \"DOGE\"",
  "hint": "Try: ETH, BTC, SOL, LINK, UNI, AAVE"
}

Caching

• 30-second cache TTL on all paid endpoints
• Identical requests within 30s are free (no payment, no rate limit count)
• Cache key = endpoint + query params (not wallet-specific)
• Cache headers: X-Cache: HIT or X-Cache: MISS

Rate Limits

• 500 requests/minute per IP address
• Cached responses do not count toward rate limit
• Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset