GET /trades

Returns recent trade history with pagination. Ordered from present to past.

Request

Query Parameters:

Name	Type	Required	Description
`marketId`	number	No	Filter by market ID
`makerId`	number	No	Filter by maker account ID
`takerId`	number	No	Filter by taker account ID
`takerSide`	string	No	Filter by taker side: `ask` or `bid`
`since`	string	No	Start timestamp (RFC3339); defaults to UNIX epoch
`until`	string	No	End timestamp (RFC3339); defaults to current time
`startInclusive`	number	No	Pagination cursor for fetching next page
`pageSize`	number	No	Maximum trades to return (default: 50, max: 50)


# Recent trades for a market
curl "https://zo-mainnet.n1.xyz/trades?marketId=0&pageSize=10"
 
# Trades for a specific maker with time range
curl "https://zo-mainnet.n1.xyz/trades?makerId=12345&since=2024-01-01T00:00:00Z&until=2024-01-02T00:00:00Z"
 
# Filter by taker side
curl "https://zo-mainnet.n1.xyz/trades?marketId=0&takerSide=bid&pageSize=50"

Response


{
  "items": [
    {
      "time": "…",
      "actionId": 1,
      "tradeId": 1,
      "takerId": 1,
      "takerSide": "ask",
      "makerId": 1,
      "marketId": 1,
      "orderId": 1,
      "price": 1,
      "baseSize": 1,
      "makerFee": 0.01,
      "takerFee": 0.035
    }
  ],
  "nextStartInclusive": null
}

Response Fields

PageResult Object

Field	Type	Description
`items`	Trade[]	Array of trade objects
`nextStartInclusive`	number \| null	Pagination cursor for next page. If `null`, no more data.

Trade Object

Field	Type	Description
`time`	string	Trade timestamp (RFC3339/ISO 8601)
`actionId`	number	Action ID that caused this trade
`tradeId`	number	Unique trade identifier
`takerId`	number	Taker account ID
`takerSide`	string	Taker side: `bid` (buy) or `ask` (sell)
`makerId`	number	Maker account ID
`marketId`	number	Market where trade occurred
`orderId`	number	Order ID of the maker order
`price`	number	Trade execution price
`baseSize`	number	Trade size in base asset
`makerFee`	number \| null	Fee paid by the maker (in quote asset). May be absent on older trades.
`takerFee`	number \| null	Fee paid by the taker (in quote asset). May be absent on older trades.

Pagination

To fetch all trades, use the nextStartInclusive cursor:


import requests
 
def fetch_all_trades(market_id: int, since: str, until: str):
    all_trades = []
    cursor = None
    
    while True:
        params = {
            "marketId": market_id,
            "since": since,
            "until": until,
            "pageSize": 50
        }
        if cursor is not None:
            params["startInclusive"] = cursor
        
        response = requests.get("https://zo-mainnet.n1.xyz/trades", params=params)
        data = response.json()
        
        all_trades.extend(data["items"])
        
        cursor = data.get("nextStartInclusive")
        if cursor is None:
            break
    
    return all_trades
 
trades = fetch_all_trades(0, "2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z")
print(f"Total trades: {len(trades)}")

Example: Python


import requests
from datetime import datetime
 
response = requests.get(
    "https://zo-mainnet.n1.xyz/trades",
    params={"marketId": 0, "pageSize": 20}
)
data = response.json()
 
print("Recent Trades:")
for trade in data["items"]:
    time = datetime.fromisoformat(trade["time"].replace("Z", "+00:00"))
    side = "BUY" if trade["takerSide"] == "bid" else "SELL"
    print(f"  {time:%H:%M:%S} | {side:4} | ${trade['price']:,.1f} x {trade['baseSize']:.4f}")

Fetching Trade History for Your Account


import requests
 
# Replace with your account ID
my_account_id = 12345
 
# Trades where you were the maker
maker_trades = requests.get(
    "https://zo-mainnet.n1.xyz/trades",
    params={"makerId": my_account_id, "pageSize": 50}
).json()
 
# Trades where you were the taker
taker_trades = requests.get(
    "https://zo-mainnet.n1.xyz/trades",
    params={"takerId": my_account_id, "pageSize": 50}
).json()
 
print(f"Maker trades: {len(maker_trades['items'])}")
print(f"Taker trades: {len(taker_trades['items'])}")