API Reference

Integrate real-world asset execution cost comparison into your application. Query live data from multiple perpetual DEXs with a single API call.

Introduction

The Real World Perps API provides programmatic access to execution cost comparisons across multiple perpetual DEXs. Use it to find the best venue for trading real-world assets like gold, forex, and equities.

The API returns real-time data including slippage estimates, fee calculations, liquidity checks, and identifies the lowest-cost venue for your trade parameters.

Base URL

All API requests should be made to the following base URL:

https://api.realworldperps.xyz

Authentication

The API is currently open and does not require authentication. This may change in the future for rate limiting purposes.

# No authentication required
curl "https://api.realworldperps.xyz/api/compare/XAU?size=100000&direction=long"

Endpoints

The API currently provides one main endpoint for comparing execution costs across all supported exchanges.

Compare Costs

GET/api/compare/{asset}

Compare execution costs for a specific asset across all supported perpetual DEXs. Returns real-time slippage, fees, and liquidity data for each exchange.

Request Parameters

Path Parameters

Parameter	Type	Description
`asset`required	string	Asset identifier (e.g., XAU, XAG, EURUSD, AAPL)

Query Parameters

Parameter	Type	Description
`size`required	number	Order size in USD (e.g., 100000 for $100,000)
`direction`required	string	Trade direction: "long" or "short"
`order_type`	string	Order type: "taker" (default) or "maker"

Example Request

curl "https://api.realworldperps.xyz/api/compare/XAU?size=100000&direction=long&order_type=taker"

Response Schema

The response contains metadata about the request, results from each exchange, and the winning (lowest cost) venue.

Top-Level Fields

Parameter	Type	Description
`asset`	string	Full asset name (e.g., "XAU/USD")
`symbol_key`	string	Asset identifier used in request
`order_size_usd`	number	Requested order size in USD
`order_type`	string	Order type (taker/maker)
`direction`	string	Trade direction (long/short)
`winner`	string	Exchange with lowest total cost
`winner_cost_bps`	number	Winning exchange total cost in bps
`symbols`	object	Asset symbol mapping for each exchange
`hyperliquid`	object \| null	Hyperliquid exchange result
`lighter`	object \| null	Lighter exchange result
`aster`	object \| null	Aster exchange result
`avantis`	object \| null	Avantis exchange result
`ostium`	object \| null	Ostium exchange result
`extended`	object \| null	Extended exchange result
`edgex`	object \| null	EdgeX exchange result
`grvt`	object \| null	GRVT exchange result

Exchange Fields

Each exchange object contains the following fields. Some fields may be null or absent if not applicable to that exchange.

Cost Fields (in basis points)

Parameter	Type	Description
`opening_slippage_bps`	number	Slippage cost when opening position
`closing_slippage_bps`	number	Slippage cost when closing position
`open_fee_bps`	number	Fee charged on open
`close_fee_bps`	number	Fee charged on close
`total_cost_bps`	number	Total round-trip cost
`effective_spread_bps`	number	Effective bid-ask spread

Holding Fee Fields

Holding fees are based on the platform's hourly funding/margin rate extrapolated to 24 hours. Symmetric exchanges return a single rate; directional exchanges (Avantis, Ostium) return separate long/short rates.

Parameter	Type	Description
`holding_fee_1h_pct`	number	Hourly holding fee as % of notional (symmetric exchanges)
`holding_fee_24h_pct`	number	24-hour holding fee as % of notional (symmetric exchanges)
`holding_fee_1h_long_pct`	number	Hourly holding fee for longs (directional exchanges)
`holding_fee_1h_short_pct`	number	Hourly holding fee for shorts (directional exchanges)
`holding_fee_24h_long_pct`	number	24-hour holding fee for longs (directional exchanges)
`holding_fee_24h_short_pct`	number	24-hour holding fee for shorts (directional exchanges)

Execution Fields

Parameter	Type	Description
`executed`	boolean \| string	Whether full order can be filled. "PARTIAL" if partial fill.
`filled`	boolean	True if order fully filled
`filled_usd`	number	Amount that can be filled in USD
`unfilled_usd`	number	Amount that cannot be filled
`max_leverage`	number	Maximum leverage available

Price Fields

Parameter	Type	Description
`mid_price`	number	Mid-market price
`best_bid`	number	Best bid price (order book exchanges)
`best_ask`	number	Best ask price (order book exchanges)
`symbol`	string	Exchange-specific symbol
`timestamp`	number	Unix timestamp of data

Buy/Sell Breakdown

The buy and sell objects contain per-side execution details:

Parameter	Type	Description
`avg_price`	number	Average execution price for this side
`slippage_bps`	number	Slippage for this side in bps
`filled_usd`	number	Amount filled for this side
`unfilled_usd`	number	Amount unfilled for this side
`levels_used`	number	Order book levels consumed

Examples

Full Response Example

Response for a $100,000 long position on Gold (XAU):

{
  "asset": "XAU/USD",
  "symbol_key": "XAU",
  "order_size_usd": 100000.0,
  "order_type": "taker",
  "direction": "long",
  "winner": "ostium",
  "winner_cost_bps": 2.89,
  "symbols": {
    "hyperliquid": "xyz:GOLD",
    "lighter": "XAU",
    "aster": "XAUUSDT",
    "avantis": "XAU",
    "ostium": "XAUUSD",
    "extended": "XAU-USD",
    "edgex": "XAU-USD",
    "grvt": "XAU_USDT"
  },
  "hyperliquid": {
    "exchange": "hyperliquid",
    "symbol": "xyz:GOLD",
    "executed": true,
    "filled": true,
    "filled_usd": 100000.0,
    "opening_slippage_bps": 1.06,
    "closing_slippage_bps": 1.03,
    "open_fee_bps": 9.0,
    "close_fee_bps": 9.0,
    "total_cost_bps": 20.09,
    "holding_fee_1h_pct": 0.00018,
    "holding_fee_24h_pct": 0.0042,
    "max_leverage": 20,
    "mid_price": 5139.05,
    "best_bid": 5139.0,
    "best_ask": 5139.1,
    "timestamp": 1771947188.14,
    "buy": {
      "avg_price": 5139.59,
      "slippage_bps": 1.06,
      "filled_usd": 100000.0,
      "levels_used": 6
    },
    "sell": {
      "avg_price": 5138.51,
      "slippage_bps": 1.03,
      "filled_usd": 100000.0,
      "levels_used": 5
    }
  },
  "ostium": {
    "exchange": "ostium",
    "symbol": "XAUUSD",
    "executed": true,
    "filled": true,
    "opening_slippage_bps": 0.69,
    "closing_slippage_bps": 0.69,
    "open_fee_bps": 1.5,
    "close_fee_bps": 0.0,
    "total_cost_bps": 2.89,
    "holding_fee_1h_long_pct": 0.00021,
    "holding_fee_1h_short_pct": -0.00015,
    "holding_fee_24h_long_pct": 0.005,
    "holding_fee_24h_short_pct": -0.0036,
    "max_leverage": 100.0,
    "mid_price": 5137.39,
    "timestamp": 1771947189.58
  }
  // ... other exchanges (lighter, aster, avantis, extended, edgex, grvt)
}

JavaScript Example

const response = await fetch(
  'https://api.realworldperps.xyz/api/compare/XAU?size=100000&direction=long'
);
const data = await response.json();

console.log(`Best venue: ${data.winner}`);
console.log(`Total cost: ${data.winner_cost_bps} bps`);

// Calculate USD cost
const usdCost = (data.order_size_usd * data.winner_cost_bps) / 10000;
console.log(`USD cost: $${usdCost.toFixed(2)}`);

Python Example

import requests

response = requests.get(
    'https://api.realworldperps.xyz/api/compare/XAU',
    params={
        'size': 100000,
        'direction': 'long',
        'order_type': 'taker'
    }
)
data = response.json()

print(f"Best venue: {data['winner']}")
print(f"Total cost: {data['winner_cost_bps']:.2f} bps")

# Get individual exchange costs
for exchange in ['hyperliquid', 'lighter', 'aster', 'avantis', 'ostium', 'extended', 'edgex', 'grvt']:
    if data.get(exchange):
        cost = data[exchange].get('total_cost_bps', 'N/A')
        print(f"  {exchange}: {cost} bps")

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Status Code	Meaning
`200`	Success - comparison data returned
`400`	Bad Request - invalid parameters
`404`	Not Found - asset not supported
`500`	Server Error - try again later
`503`	Service Unavailable - exchange API down

Error Response Format

{
  "error": "Invalid asset",
  "message": "Asset 'INVALID' is not supported",
  "supported_assets": ["XAU", "XAG", "EURUSD", "GBPUSD", ...]
}

Supported Assets

The following assets are supported. Use the asset key in the API path.

Asset Key	Name	Category
`XAU`	Gold	Commodities
`XAG`	Silver	Commodities
`EURUSD`	Euro / US Dollar	Forex
`GBPUSD`	British Pound / US Dollar	Forex
`USDJPY`	US Dollar / Japanese Yen	Forex
`AAPL`	Apple Inc.	Equities
`MSFT`	Microsoft Corporation	Equities
`GOOG`	Alphabet Inc.	Equities
`AMZN`	Amazon.com Inc.	Equities
`META`	Meta Platforms Inc.	Equities
`NVDA`	NVIDIA Corporation	Equities
`TSLA`	Tesla Inc.	Equities
`SPY`	S&P 500 ETF	Indices
`QQQ`	Nasdaq 100 ETF	Indices
`COIN`	Coinbase Global Inc.	Equities

Rate Limits

The API currently has generous rate limits suitable for most use cases:

20 requests per 10 seconds per IP address

If you need higher limits for production use, please contact us.

Rate limit headers are included in responses:

X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Need help? Check the methodology docs or reach out.

← Back to comparison tool