API Documentation

Access live BasicSwap DEX orderbook data through our REST API.

Contents

Getting Started
Authentication
Rate Limits
API Endpoints
Error Handling

Getting Started

Create an account at account.basicswap.bid
Generate an API key from your dashboard
Include the key in your requests using the X-API-Key header

Quick Example

curl -H "X-API-Key: bsw_live_your_key_here" \
  https://api.basicswap.bid/v1/orderbook

Authentication

All API requests require authentication via an API key. Include your key in the X-API-Key header:

X-API-Key: bsw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

Rate Limits

Tier	Limit	Price
Free	5 requests/minute	$0
Paid (usage-based)	Unlimited	$0.001 per request after free tier

Rate limit headers are included in all responses:

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 2025-01-31T12:35:00Z

API Endpoints

GET /v1/status

Get data freshness status. Useful for checking if the orderbook data is current.

Response

{
  "status": "fresh",
  "lastSyncAt": "2025-01-31T12:34:56Z",
  "ageSeconds": 12,
  "offerCount": 47
}

GET /v1/orderbook

Get the full orderbook snapshot with all active offers.

Response

{
  "data": [
    {
      "offerId": "abc123...",
      "coinFrom": "Bitcoin",
      "coinTo": "Monero",
      "amountFrom": "0.5",
      "amountTo": "85.5",
      "rate": "171.0",
      "minSwap": "0.01",
      "createdAt": 1706700000000,
      "expiresAt": 1706786400000
    }
  ],
  "meta": {
    "lastSyncAt": "2025-01-31T12:34:56Z",
    "offerCount": 47,
    "dataAgeSeconds": 12
  }
}

GET /v1/orderbook/:pair

Get offers for a specific trading pair.

Parameters

Name	Type	Description
`pair`	string	Trading pair in format `coin1-coin2` using full coin names (e.g., `bitcoin-monero`)

Example

GET /v1/orderbook/bitcoin-monero

Available coins: Bitcoin, Monero, Litecoin, Particl, Particl Blind, Particl Anon, Bitcoin Cash. Use the /v1/pairs endpoint to get the current list.

GET /v1/pairs

Get all available trading pairs with statistics.

Response

{
  "data": [
    {
      "pair": "BITCOIN-MONERO",
      "coinFrom": "BITCOIN",
      "coinTo": "MONERO",
      "offerCount": 12,
      "avgRate": 171.5,
      "minRate": 168.0,
      "maxRate": 175.0,
      "totalVolume": 2.5
    }
  ],
  "meta": { ... }
}

GET /v1/stats

Get aggregate orderbook statistics.

Response

{
  "data": {
    "totalOffers": 47,
    "totalPairs": 8,
    "totalVolume": 15.5,
    "uniqueCoins": ["Bitcoin", "Monero", "Litecoin", "Particl", "Bitcoin Cash"],
    "coinCount": 5
  },
  "meta": { ... }
}

Error Handling

Errors are returned with appropriate HTTP status codes:

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid API key
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Format

{
  "error": "Rate limit exceeded",
  "limit": "5 requests per minute",
  "retryAfter": 45,
  "resetAt": "2025-01-31T12:35:00Z",
  "upgradeHint": "Upgrade to a paid plan for higher limits"
}

Support

For questions or issues, please visit BasicSwap GitHub.