Developer Documentation

TidoEx Public API V2

Exposing public and standard endpoints designed for data aggregators, algorithmic trading, and developers. No authentication or API keys are required to query public data.

API Specifications

Base URL:/api/v2

Rate Limit:30 req/min

Auth:Public (None)

Auth:X-API-Key

Getting Started

All endpoints under this specification reside on port 8080 under the /api/v2/ namespace. Rate limits are tracked automatically per IP address via standard token-bucket algorithms. If you exceed the maximum threshold of 30 requests per minute, the API Gateway returns a 429 Too Many Requests error containing a descriptive JSON body.

Private API Authentication

Private endpoints require an API key passed via the X-API-Key HTTP header. Generate your key by calling POST /api/v2/private/api-keys (initially you will need to create a key via the database or admin panel). All private endpoints are rate-limited to 30 requests per minute per IP.

Example Request

# All private endpoints require this header:
X-API-Key: YOUR_API_KEY

# Example:
curl -X GET "http://localhost:8080/api/v2/private/balances" \
  -H "X-API-Key: YOUR_API_KEY"

Private Endpoints

GET

/private/balances

Retrieve all wallet balances for the authenticated user. Returns each asset with available and locked amounts.

Auth: X-API-Key

Rate Limit: 30 requests/minute

curl -X GET "http://localhost:8080/api/v2/private/balances" \
  -H "X-API-Key: YOUR_API_KEY"

Response (200 OK)

[
  {
    "asset": "USDT",
    "balance": "1250.500000000000000000",
    "locked_balance": "100.000000000000000000"
  },
  {
    "asset": "BTC",
    "balance": "0.500000000000000000",
    "locked_balance": "0.100000000000000000"
  }
]

GET

/private/history

Retrieve the authenticated user's complete transaction history including deposits, withdrawals, and faucet claims. Sorted by most recent first.

Auth: X-API-Key

Rate Limit: 30 requests/minute

curl -X GET "http://localhost:8080/api/v2/private/history" \
  -H "X-API-Key: YOUR_API_KEY"

Response (200 OK)

[
  {
    "id": 1,
    "type": "WITHDRAWAL",
    "chain": "ETH",
    "asset": "ETH",
    "amount": 0.5,
    "fee": 0.005,
    "address": "0x...",
    "status": "CONFIRMED",
    "timestamp": "2026-07-01T10:00:00Z"
  },
  {
    "id": 2,
    "type": "DEPOSIT",
    "chain": "BTC",
    "asset": "BTC",
    "amount": 0.1,
    "tx_hash": "abc...",
    "status": "CONFIRMED",
    "timestamp": "2026-06-30T22:00:00Z"
  }
]

POST

/private/withdraw

Submit a withdrawal request. For on-chain withdrawals the funds are sent to the specified blockchain address; for manual withdrawals the funds are credited internally.

Auth: X-API-Key

Rate Limit: 30 requests/minute

Request Body

Param	Type	Required
asset	string	Yes
amount	number	Yes
chain	string	No
to_address	string	No

curl -X POST "http://localhost:8080/api/v2/private/withdraw" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "ETH",
    "amount": 0.5,
    "chain": "ETH",
    "to_address": "0x..."
  }'

Response (200 OK)

{
  "message": "Withdrew 0.500000 ETH successfully (Fee paid: 0.005000 ETH)"
}

GET

/private/deposit/address

Retrieve or generate a deposit address for a specific blockchain. If an address already exists for the user and chain, it is returned; otherwise a new address is derived.

Auth: X-API-Key

Rate Limit: 30 requests/minute

Query Parameters

Param	Type	Required
chain	string	Yes

curl -X GET "http://localhost:8080/api/v2/private/deposit/address?chain=ETH" \
  -H "X-API-Key: YOUR_API_KEY"

Response (200 OK)

{
  "address": "0x...",
  "exists": true
}

POST

/private/order

Place a new order on the spot order book. Supports LIMIT, MARKET, STOP_LIMIT, and STOP_MARKET order types. The order is immediately matched against the order book and any resulting trades are returned.

Auth: X-API-Key

Rate Limit: 30 requests/minute

Request Body

Param	Type	Required
pair_id	integer	Yes
side	string	Yes
type	string	Yes
price	number	No
amount	number	Yes
trigger_price	number	No

curl -X POST "http://localhost:8080/api/v2/private/order" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pair_id": 1,
    "side": "BUY",
    "type": "LIMIT",
    "price": 30000.00,
    "amount": 0.01
  }'

Response (200 OK)

{
  "order": {
    "id": 12345,
    "pair_id": 1,
    "side": "BUY",
    "type": "LIMIT",
    "price": 30000.00,
    "amount": 0.01,
    "filled_amount": 0.00,
    "status": "OPEN"
  },
  "trades": []
}

POST

/private/cancel

Cancel an open order by its ID. Only the order owner can cancel their own orders. Locked funds are immediately unlocked upon cancellation.

Auth: X-API-Key

Rate Limit: 30 requests/minute

Request Body

Param	Type	Required
order_id	integer	Yes

curl -X POST "http://localhost:8080/api/v2/private/cancel" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id": 12345}'

Response (200 OK)

{
  "message": "Order cancelled successfully"
}

GET

/private/orders

Retrieve the authenticated user's orders. Supports filtering by active status and trading pair, with pagination support.

Auth: X-API-Key

Rate Limit: 30 requests/minute

Query Parameters

Param	Type	Required
active	string	No (Default: false)
pair_id	integer	No (Default: )
limit	integer	No (Default: 10)
offset	integer	No (Default: 0)

curl -X GET "http://localhost:8080/api/v2/private/orders?active=true&limit=5" \
  -H "X-API-Key: YOUR_API_KEY"

Response (200 OK)

{
  "orders": [
    {
      "id": 12345,
      "pair_id": 1,
      "side": "BUY",
      "type": "LIMIT",
      "price": 30000.00,
      "amount": 0.01,
      "filled_amount": 0.00,
      "status": "OPEN",
      "created_at": "2026-07-01T10:00:00Z"
    }
  ],
  "has_more": false
}

GET

/private/trades

Retrieve the authenticated user's executed trade history. Supports filtering by trading pair with pagination.

Auth: X-API-Key

Rate Limit: 30 requests/minute

Query Parameters

Param	Type	Required
pair_id	integer	No (Default: )
limit	integer	No (Default: 10)
offset	integer	No (Default: 0)

curl -X GET "http://localhost:8080/api/v2/private/trades?limit=5" \
  -H "X-API-Key: YOUR_API_KEY"

Response (200 OK)

{
  "trades": [
    {
      "id": 1420,
      "pair_id": 1,
      "side": "BUY",
      "price": 30086.52,
      "amount": 0.003387,
      "created_at": "2026-07-01T10:00:00Z"
    }
  ],
  "has_more": false
}

GET

/private/api-keys

List all API keys associated with your account. Optionally create a new API key by sending a POST request with a name.

Auth: X-API-Key

Rate Limit: 30 requests/minute

# List keys
curl -X GET "http://localhost:8080/api/v2/private/api-keys" \
  -H "X-API-Key: YOUR_API_KEY"

# Create a new key
curl -X POST "http://localhost:8080/api/v2/private/api-keys" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Trading Bot"}'

Response (200 OK)

// GET response (list keys):
[
  {
    "id": 1,
    "api_key": "abc123...",
    "name": "My Trading Bot",
    "is_active": true,
    "created_at": "2026-07-01T10:00:00Z",
    "last_used_at": null
  }
]

// POST response (create key):
{
  "api_key": "newly_generated_key_here",
  "name": "My Trading Bot",
  "message": "Store this key securely — it will not be shown again"
}

Public API — No Auth Required

All market data endpoints below are completely public — no authentication needed. The /gc/ endpoints serve CoinGecko-formatted data for exchange integration. The /cmc/ endpoints serve CoinMarketCap-formatted data for their exchange tracker. Just make GET requests and receive JSON.

Example Request

# No headers, no auth — just call the endpoint:
curl -X GET "http://localhost:8080/api/v2/markets"

# Endpoint categories:
# /pairs, /markets, /orderbook, /trades — core market data
# /amm/pools, /amm/swaps               — AMM liquidity data
# /gc/*                                — CoinGecko integration
# /cmc/*                               — CoinMarketCap integration

Public Endpoints

GET

/pairs

Retrieve a list of all active trading pairs supported by the exchange. Perfect for mapping asset ticker symbols to exchange pairs.

Rate Limit: 30 requests/minute

curl -X GET "http://localhost:8080/api/v2/pairs"

Response (200 OK)

[
  {
    "market_id": "BTC_USDT",
    "base": "BTC",
    "target": "USDT"
  },
  {
    "market_id": "ETH_USDT",
    "base": "ETH",
    "target": "USDT"
  },
  {
    "market_id": "LINK_USDT",
    "base": "LINK",
    "target": "USDT"
  }
]

GET

/markets

Retrieve 24-hour pricing and volume summary statistics for all active trading pairs. Includes bid/ask spreads and aliases for compatibility with CoinGecko and CoinMarketCap.

Rate Limit: 30 requests/minute

Query Parameters

Param	Type	Required
market_id	string	No (Default: )

curl -X GET "http://localhost:8080/api/v2/markets"

Response (200 OK)

[
  {
    "market_id": "BTC_USDT",
    "base_currency": "BTC",
    "target_currency": "USDT",
    "last_price": "30086.52",
    "base_volume": "0.007774",
    "target_volume": "233.87",
    "bid": "29896.49",
    "ask": "30150.00",
    "high": "30086.52",
    "low": "30063.13",
    "quote_volume": "233.87",
    "lowest_ask": "30150.00",
    "highest_bid": "29896.49",
    "high_24h": "30086.52",
    "low_24h": "30063.13"
  }
]

GET

/orderbook

Retrieve a combined order book (Limit Order Book + virtual Automated Market Maker liquidity levels) for a specific trading pair.

Rate Limit: 30 requests/minute

Query Parameters

Param	Type	Required
market_id	string	Yes
depth	integer	No (Default: 100)

curl -X GET "http://localhost:8080/api/v2/orderbook?market_id=BTC_USDT&depth=2"

Response (200 OK)

{
  "market_id": "BTC_USDT",
  "timestamp": 1780821194,
  "bids": [
    ["29896.4929", "0.0125"],
    ["29850.0000", "0.0884"]
  ],
  "asks": [
    ["30149.9999", "0.0169"],
    ["30196.9601", "0.0124"]
  ]
}

GET

/trades

Retrieve trade history logs for a specific trading pair. Resolves the trade direction (buy/sell) using taker order sides or price tick analysis.

Rate Limit: 30 requests/minute

Query Parameters

Param	Type	Required
market_id	string	Yes
limit	integer	No (Default: 100)

curl -X GET "http://localhost:8080/api/v2/trades?market_id=BTC_USDT&limit=2"

Response (200 OK)

[
  {
    "trade_id": "1420",
    "price": "30086.52",
    "base_volume": "0.003387",
    "target_volume": "101.90",
    "trade_timestamp": 1780803330,
    "type": "buy"
  },
  {
    "trade_id": "1419",
    "price": "30086.52",
    "base_volume": "0.003387",
    "target_volume": "101.90",
    "trade_timestamp": 1780803330,
    "type": "buy"
  }
]

GET

/historical_trades

Retrieve historical trade logs for a specific trading pair. Allows pagination using trade IDs or time ranges.

Rate Limit: 30 requests/minute

Query Parameters

Param	Type	Required
market_id	string	Yes
start_time	integer	No (Default: )
end_time	integer	No (Default: )
from_id	integer	No (Default: )
limit	integer	No (Default: 100)

curl -X GET "http://localhost:8080/api/v2/historical_trades?market_id=BTC_USDT&limit=2"

Response (200 OK)

[
  {
    "trade_id": "1420",
    "price": "30086.52",
    "base_volume": "0.003387",
    "target_volume": "101.90",
    "trade_timestamp": 1780803330,
    "type": "buy"
  },
  {
    "trade_id": "1419",
    "price": "30086.52",
    "base_volume": "0.003387",
    "target_volume": "101.90",
    "trade_timestamp": 1780803330,
    "type": "buy"
  }
]

GET

/amm/pools

Retrieve a list of all active Automated Market Maker (AMM) pools, including their current base/quote reserves and total pool shares.

Rate Limit: 30 requests/minute

curl -X GET "http://localhost:8080/api/v2/amm/pools"

Response (200 OK)

[
  {
    "pool_id": "12",
    "market_id": "BTC_USDT",
    "base_asset": "BTC",
    "quote_asset": "USDT",
    "reserve_base": "4.996113",
    "reserve_quote": "150116.8410",
    "total_shares": "150000"
  }
]

GET

/amm/swaps

Retrieve recent swap records executed specifically on AMM pools (excluding standard order book matches).

Rate Limit: 30 requests/minute

Query Parameters

Param	Type	Required
market_id	string	No (Default: )
limit	integer	No (Default: 100)

curl -X GET "http://localhost:8080/api/v2/amm/swaps?limit=1"

Response (200 OK)

[
  {
    "swap_id": "1420",
    "market_id": "BTC_USDT",
    "price": "30086.52",
    "base_volume": "0.003387",
    "target_volume": "101.90",
    "swap_timestamp": 1780803330,
    "type": "buy"
  }
]

GET

/gc/tickers

Retrieve all ticker data formatted for CoinGecko integration. Returns a tickers envelope with ticker_id, base_currency, target_currency, last_price, base_volume, target_volume, bid, ask, high, and low for every active trading pair.

Rate Limit: 30 requests/minute

curl -X GET "http://localhost:8080/api/v2/gc/tickers"

Response (200 OK)

{
  "tickers": [
    {
      "ticker_id": "BTC_USDT",
      "base_currency": "BTC",
      "target_currency": "USDT",
      "last_price": "30086.52",
      "base_volume": "0.007774",
      "target_volume": "233.87",
      "bid": "29896.49",
      "ask": "30150.00",
      "high": "30086.52",
      "low": "30063.13"
    }
  ]
}

GET

/gc/orderbook

Retrieve order book depth for a specific trading pair formatted for CoinGecko. Uses ticker_id parameter instead of market_id.

Rate Limit: 30 requests/minute

Query Parameters

Param	Type	Required
ticker_id	string	Yes
depth	integer	No (Default: 100)

curl -X GET "http://localhost:8080/api/v2/gc/orderbook?ticker_id=BTC_USDT&depth=2"

Response (200 OK)

{
  "ticker_id": "BTC_USDT",
  "timestamp": 1780821194,
  "bids": [
    ["29896.49", "0.0125"],
    ["29850.00", "0.0884"]
  ],
  "asks": [
    ["30150.00", "0.0169"],
    ["30196.96", "0.0124"]
  ]
}

GET

/gc/historical_trades

Retrieve historical trade data formatted for CoinGecko integration. Supports pagination via start_time, end_time, and from_id parameters.

Rate Limit: 30 requests/minute

Query Parameters

Param	Type	Required
ticker_id	string	Yes
limit	integer	No (Default: 100)
start_time	integer	No (Default: )
end_time	integer	No (Default: )
from_id	integer	No (Default: )

curl -X GET "http://localhost:8080/api/v2/gc/historical_trades?ticker_id=BTC_USDT&limit=2"

Response (200 OK)

[
  {
    "trade_id": "1420",
    "price": "30086.52",
    "base_volume": "0.003387",
    "target_volume": "101.90",
    "trade_timestamp": 1780803330,
    "type": "buy"
  },
  {
    "trade_id": "1419",
    "price": "30086.52",
    "base_volume": "0.003387",
    "target_volume": "101.90",
    "trade_timestamp": 1780803330,
    "type": "buy"
  }
]

GET

/cmc/summary

Retrieve a market summary overview for all active trading pairs formatted for CoinMarketCap. Includes 24-hour price change percentage and highest/lowest prices for each pair.

Rate Limit: 30 requests/minute

curl -X GET "http://localhost:8080/api/v2/cmc/summary"

Response (200 OK)

[
  {
    "trading_pairs": "BTC_USDT",
    "last_price": "30086.52",
    "lowest_ask": "30150.00",
    "highest_bid": "29896.49",
    "base_volume": "0.007774",
    "quote_volume": "233.87",
    "price_change_percent_24h": "1.25",
    "highest_price_24h": "30086.52",
    "lowest_price_24h": "30063.13"
  }
]

GET

/cmc/assets

Retrieve details for each listed asset formatted for CoinMarketCap. Includes withdrawal and deposit status, minimum withdrawal amounts, and average exchange maker/taker fees.

Rate Limit: 30 requests/minute

curl -X GET "http://localhost:8080/api/v2/cmc/assets"

Response (200 OK)

[
  {
    "name": "Bitcoin",
    "unified_cryptoasset_id": "BTC",
    "can_withdraw": true,
    "can_deposit": true,
    "min_withdraw": "0.001",
    "max_withdraw": "",
    "maker_fee": "0.0010",
    "taker_fee": "0.0020"
  },
  {
    "name": "Tether",
    "unified_cryptoasset_id": "USDT",
    "can_withdraw": true,
    "can_deposit": true,
    "min_withdraw": "10",
    "max_withdraw": "",
    "maker_fee": "0.0010",
    "taker_fee": "0.0020"
  }
]

GET

/cmc/ticker

Retrieve 24-hour pricing and volume summary for each market pair formatted for CoinMarketCap. Optionally filter by market_pair.

Rate Limit: 30 requests/minute

Query Parameters

Param	Type	Required
market_pair	string	No (Default: )

curl -X GET "http://localhost:8080/api/v2/cmc/ticker"

Response (200 OK)

[
  {
    "base_id": "BTC",
    "quote_id": "USDT",
    "last_price": "30086.52",
    "quote_volume": "233.87",
    "base_volume": "0.007774",
    "isFrozen": "0"
  }
]

GET

/cmc/orderbook

Retrieve order book depth for a specific trading pair formatted for CoinMarketCap. Uses market_pair parameter.

Rate Limit: 30 requests/minute

Query Parameters

Param	Type	Required
market_pair	string	Yes
depth	integer	No (Default: 100)

curl -X GET "http://localhost:8080/api/v2/cmc/orderbook?market_pair=BTC_USDT&depth=2"

Response (200 OK)

{
  "timestamp": 1780821194,
  "bids": [
    ["29896.49", "0.0125"],
    ["29850.00", "0.0884"]
  ],
  "asks": [
    ["30150.00", "0.0169"],
    ["30196.96", "0.0124"]
  ]
}

GET

/cmc/trades

Retrieve recently completed trades for a specific trading pair formatted for CoinMarketCap.

Rate Limit: 30 requests/minute

Query Parameters

Param	Type	Required
market_pair	string	Yes
limit	integer	No (Default: 100)

curl -X GET "http://localhost:8080/api/v2/cmc/trades?market_pair=BTC_USDT&limit=2"

Response (200 OK)

[
  {
    "trade_id": "1420",
    "price": "30086.52",
    "base_volume": "0.003387",
    "target_volume": "101.90",
    "trade_timestamp": 1780803330,
    "type": "buy"
  },
  {
    "trade_id": "1419",
    "price": "30086.52",
    "base_volume": "0.003387",
    "target_volume": "101.90",
    "trade_timestamp": 1780803330,
    "type": "buy"
  }
]