Oracle API

The 0xio Oracle provides real-time price feeds, swap quotes, and historical price data for the 0xio ecosystem. Prices are aggregated from multiple sources (CoinGecko + DexScreener) with anomaly detection and stored in PostgreSQL for historical chart data.

Base URL

https://oracle.0xio.xyz

Authentication

Most API endpoints require an API key. Get your key from the Developer Portal. Include the key in the x-api-key header:

x-api-key: 0xio-abc123def456-oracle

Keep your API key secret. Never expose it in client-side code or public repositories.

Protected vs Public Endpoints

Endpoint	Auth Required
`GET /health`	No
`GET /api/health`	No
`GET /api/keys`	Signature
`POST /api/keys`	Signature
`GET /api/price/oct/details`	Yes
`GET /api/price/twap`	Yes
`GET /api/price/:symbol`	Yes
`GET /api/prices`	Yes
`GET /api/quote`	Yes
`GET /api/reserves`	Yes
`GET /api/chart/history`	Yes
`POST /api/simulate-trade`	Yes
`POST /api/liquidity`	Yes
`DELETE /api/keys`	Yes

Health Check

Full Health Check

GET /health

Returns detailed service status including database and cache connectivity. Response:

{
  "status": "healthy",
  "timestamp": "2025-01-26T12:00:00+00:00",
  "version": "2.0.0",
  "services": {
    "database": "connected",
    "redis": "connected"
  },
  "environment": "production"
}

Simple Liveness Probe

GET /api/health

Returns a simple response for load balancer health checks. Response:

{
  "status": "ok",
  "timestamp": 1706270400000
}

Prices

Get Token Price

GET /api/price/:symbol

Get the current spot price for a specific token. Parameters:

Parameter	Type	Description
`symbol`	path	Token symbol (e.g., `OCT`, `USDC`, `SOL`, `ETH`)

Example:

curl -H "x-api-key: YOUR_KEY" \
  https://oracle.0xio.xyz/api/price/OCT

Response:

{
  "symbol": "OCT",
  "price": 0.024816,
  "source": "aggregated(coingecko+dexscreener)"
}

The source field indicates where the price came from:

aggregated(coingecko+dexscreener): Multi-source aggregation with anomaly detection (OCT / wOCT)
pyth: Pyth Network oracle feed (SOL, ETH, and other non-OCT symbols)
static: Hardcoded value (stablecoins USDC / USDT)

Get All Prices

GET /api/prices

Get current prices for all supported tokens (OCT, WOCT, USDC, USDT, SOL, ETH). Example:

curl -H "x-api-key: YOUR_KEY" \
  https://oracle.0xio.xyz/api/prices

Response:

{
  "OCT": 0.024816,
  "WOCT": 0.024816,
  "USDC": 1.0,
  "USDT": 1.0,
  "SOL": 180.50,
  "ETH": 3200.00
}

Get OCT Detailed Market Data

GET /api/price/oct/details

Get full aggregated market data for OCT including 24h change, volume, liquidity, and source breakdown. Example:

curl -H "x-api-key: YOUR_KEY" \
  https://oracle.0xio.xyz/api/price/oct/details

Response:

{
  "symbol": "OCT",
  "priceUsd": 0.024816,
  "priceChange24h": -2.15,
  "volume24h": 12500.00,
  "liquidityUsd": 85000.00,
  "source": "aggregated(coingecko+dexscreener)",
  "confidence": "high",
  "spreadPct": 0.8,
  "allSources": {
    "coingecko": 0.024800,
    "dexscreener": 0.024832
  },
  "ethUsd": 1780.50,
  "timestamp": 1745312400000
}

Get TWAP Prices

GET /api/price/twap

Get 5-minute time-weighted average prices for OCT and ETH alongside the current spot, plus the OCT spot-vs-TWAP deviation. Example:

curl -H "x-api-key: YOUR_KEY" \
  https://oracle.0xio.xyz/api/price/twap

Response:

{
  "oct": {
    "twap_5m": 0.024790,
    "spot": 0.024816,
    "deviation_pct": 0.10
  },
  "eth": {
    "twap_5m": 1779.20,
    "spot": 1780.50
  },
  "window_seconds": 300,
  "timestamp": 1745312400000
}

Trading

Get Swap Quote

GET /api/quote

Get a swap quote with expected output amount and price impact. Query Parameters:

Parameter	Type	Description
`inputMint`	string	Input token symbol
`outputMint`	string	Output token symbol
`amount`	string	Input amount (as string)

Example:

curl -H "x-api-key: YOUR_KEY" \
  "https://oracle.0xio.xyz/api/quote?inputMint=OCT&outputMint=USDC&amount=100"

Response:

{
  "inputToken": "OCT",
  "outputToken": "USDC",
  "amountIn": 100,
  "amountOut": 124.75,
  "feeAmount": 0.25,
  "priceImpact": 0.0005,
  "spotPrice": 1.25,
  "executionPrice": 1.2475,
  "route": "Solver-AMM-v1"
}

Get AMM Reserves

GET /api/reserves

Get current liquidity pool reserves. Example:

curl -H "x-api-key: YOUR_KEY" \
  https://oracle.0xio.xyz/api/reserves

Response:

{
  "reserves": {
    "OCT": 1000000,
    "USDC": 1250000,
    "USDT": 500000
  },
  "timestamp": 1706270400000
}

Simulate Trade

POST /api/simulate-trade

Simulate a trade execution against the AMM. Updates internal reserves for quote accuracy. Request Body:

{
  "inputToken": "OCT",
  "amountIn": 1000,
  "outputToken": "USDC",
  "amountOut": 1245.50
}

Response:

{
  "success": true,
  "newReserves": {
    "OCT": 1001000,
    "USDC": 1248754.50
  }
}

Update Liquidity (Admin)

POST /api/liquidity

Update liquidity reserves. Used by the watcher service to sync on-chain balances. Request Body:

{
  "reserves": {
    "OCT": 1000000,
    "USDC": 1250000
  }
}

Response:

{
  "success": true,
  "message": "Liquidity Updated",
  "currentReserves": {
    "OCT": 1000000,
    "USDC": 1250000
  },
  "newPriceOctUsdt": 1.25
}

Chart Data

Get Price History

GET /api/chart/history

Get historical price data over a configurable time range. Points are downsampled to fit the range (e.g. 30d → ~1 point per 2h). Query Parameters:

Parameter	Type	Default	Description
`pair`	string	`OCT`	Token symbol
`range`	string	`1d`	Time window: `1h`, `1d`, `7d` (`1w`), `30d` (`1m`), `1y` (`365d`)

Example:

curl -H "x-api-key: YOUR_KEY" \
  "https://oracle.0xio.xyz/api/chart/history?pair=OCT&range=30d"

Response:

[
  { "value": 1.24, "time": 1706270400 },
  { "value": 1.25, "time": 1706274000 },
  { "value": 1.26, "time": 1706277600 }
]

The time field on chart data points is a Unix timestamp in seconds (suitable for charting libraries like Lightweight Charts). Other endpoints (/health, /api/price/oct/details, /api/reserves) return timestamps in milliseconds.

API Key Management

List Your Keys

GET /api/keys

List all API keys associated with your wallet address. Requires wallet signature for privacy. Query Parameters:

Parameter	Type	Required	Description
`owner`	string	Yes	Your wallet address
`timestamp`	number	Yes	Unix timestamp
`signature`	string	Yes	Base64-encoded signature of `0xio-list-keys:{owner}:{timestamp}`
`public_key`	string	Yes	Base64-encoded Ed25519 public key

Example:

curl "https://oracle.0xio.xyz/api/keys?owner=oct1...&timestamp=170...&signature=...&public_key=..."

Response:

[
  {
    "key_masked": "0xio-abc...cle",
    "label": "Production App",
    "created_at": "2025-01-15 10:30:00"
  }
]

Generate New Key

POST /api/keys

Generate a new API key. Requires wallet signature for verification. Keys follow the format 0xio-{hex}-oracle. Request Body:

{
  "owner": "oct1abc...",
  "label": "My App Production",
  "signature": "base64_encoded_signature",
  "timestamp": 1706270400
}

Field	Type	Required	Description
`owner`	string	Yes	Your wallet address (oct1…)
`public_key`	string	Yes	The Ed25519 public key in HEX or Base64
`label`	string	No	Descriptive label for the key
`signature`	string	Yes	Base64-encoded ed25519 signature
`timestamp`	number	Yes	Unix timestamp (must be within 5 minutes)

Signature Message Format:

0xio-api-key:{owner}:{timestamp}

Example: 0xio-api-key:oct1abc123...:1706270400 Response:

{
  "status": "created",
  "key": "0xio-a1b2c3d4e5f6g7h8-oracle"
}

Store your API key securely! It will only be shown once.

Use the Developer Portal to create keys easily - it handles wallet signing automatically.

Revoke Key

DELETE /api/keys

Revoke an existing API key. The key to revoke must be provided in the header. Headers:

x-api-key: KEY_TO_REVOKE

Response:

{
  "status": "deleted"
}

Error Responses

HTTP Status	Description
400	Bad Request: invalid parameters or signature payload
401	Unauthorized: invalid or missing API key / signature
403	Forbidden: address not whitelisted for key creation
404	Not Found: token or resource not found
429	Too Many Requests: rate limited (response includes `retry_after` seconds)
500	Internal Server Error
502	Bad Gateway: upstream price source error
503	Service Unavailable: oracle data not yet initialized

Error responses use the shape { "error": "message" }, with a retry_after field added on 429.

Code Examples

JavaScript/TypeScript

const ORACLE_URL = 'https://oracle.0xio.xyz';
const API_KEY = 'your_api_key';

async function getQuote(input: string, output: string, amount: number) {
  const response = await fetch(
    `${ORACLE_URL}/api/quote?inputMint=${input}&outputMint=${output}&amount=${amount}`,
    {
      headers: { 'x-api-key': API_KEY }
    }
  );

  if (!response.ok) {
    throw new Error(`Oracle error: ${response.status}`);
  }

  return response.json();
}

// Usage
const quote = await getQuote('OCT', 'USDC', 100);
console.log(`Expected output: ${quote.amountOut} USDC`);
console.log(`Price impact: ${(quote.priceImpact * 100).toFixed(2)}%`);

Python

import requests

ORACLE_URL = 'https://oracle.0xio.xyz'
API_KEY = 'your_api_key'

def get_price(symbol: str) -> dict:
    response = requests.get(
        f'{ORACLE_URL}/api/price/{symbol}',
        headers={'x-api-key': API_KEY}
    )
    response.raise_for_status()
    return response.json()

# Usage
price = get_price('OCT')
print(f"OCT Price: ${price['price']} (source: {price['source']})")

Rust

use reqwest::header::HeaderMap;
use serde::Deserialize;

const ORACLE_URL: &str = "https://oracle.0xio.xyz";

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct QuoteResponse {
    input_token: String,
    output_token: String,
    amount_in: f64,
    amount_out: f64,
    price_impact: f64,
}

async fn get_quote(api_key: &str, input: &str, output: &str, amount: f64)
    -> Result<QuoteResponse, reqwest::Error>
{
    let mut headers = HeaderMap::new();
    headers.insert("x-api-key", api_key.parse().unwrap());

    let client = reqwest::Client::new();
    client
        .get(format!("{}/api/quote", ORACLE_URL))
        .query(&[
            ("inputMint", input),
            ("outputMint", output),
            ("amount", &amount.to_string()),
        ])
        .headers(headers)
        .send()
        .await?
        .json()
        .await
}

SDK Documentation

API Reference

Base URL

Authentication

Protected vs Public Endpoints

Health Check

Full Health Check

Simple Liveness Probe

Prices

Get Token Price

Get All Prices

Get OCT Detailed Market Data

Get TWAP Prices

Trading

Get Swap Quote

Get AMM Reserves

Simulate Trade

Update Liquidity (Admin)

Chart Data

Get Price History

API Key Management

List Your Keys

Generate New Key

Revoke Key

Error Responses

Code Examples

JavaScript/TypeScript

Python

Rust

​Base URL

​Authentication

​Protected vs Public Endpoints

​Health Check

​Full Health Check

​Simple Liveness Probe

​Prices

​Get Token Price

​Get All Prices

​Get OCT Detailed Market Data

​Get TWAP Prices

​Trading

​Get Swap Quote

​Get AMM Reserves

​Simulate Trade

​Update Liquidity (Admin)

​Chart Data

​Get Price History

​API Key Management

​List Your Keys

​Generate New Key

​Revoke Key

​Error Responses

​Code Examples

​JavaScript/TypeScript

​Python

​Rust

Base URL

Authentication

Protected vs Public Endpoints

Health Check

Full Health Check

Simple Liveness Probe

Prices

Get Token Price

Get All Prices

Get OCT Detailed Market Data

Get TWAP Prices

Trading

Get Swap Quote

Get AMM Reserves

Simulate Trade

Update Liquidity (Admin)

Chart Data

Get Price History

API Key Management

List Your Keys

Generate New Key

Revoke Key

Error Responses

Code Examples

JavaScript/TypeScript

Python

Rust