Trades API

Trades are created automatically when the matching engine pairs a buy order with a sell order. Each trade represents an executed transaction between two parties.

Authentication: X-Api-Key header required.

List Trades

Retrieve trades for your operator account.

GET /api/v1/trades

Query Parameters:

Parameter	Type	Description
marketId	string	Filter by market
outcomeId	string	Filter by outcome
cursor	string	Pagination cursor
limit	number	Page size

Example:

curl "https://polymarket.sandbox.playbatman.com/api/v1/trades?marketId=market-uuid&limit=20" \
  -H "X-Api-Key: your-api-key"

Response:

{
  "success": true,
  "data": {
    "trades": [
      {
        "id": "trade-uuid",
        "marketId": "market-uuid",
        "outcomeId": "outcome-uuid",
        "buyOrderId": "buy-order-uuid",
        "sellOrderId": "sell-order-uuid",
        "buyerOperatorId": "operator-uuid-1",
        "sellerOperatorId": "operator-uuid-2",
        "price": "0.65",
        "shares": "30",
        "buyerFee": "0.39",
        "sellerFee": "0.39",
        "createdAt": "2026-02-18T22:00:00.000Z"
      }
    ],
    "total": 128,
    "hasMore": true,
    "nextCursor": "cursor-value"
  }
}

Trade Fields

Field	Type	Description
id	string	Trade UUID
marketId	string	Market where the trade occurred
outcomeId	string	Outcome that was traded
buyOrderId	string	UUID of the buy order
sellOrderId	string	UUID of the sell order
buyerOperatorId	string	Operator who placed the buy order
sellerOperatorId	string	Operator who placed the sell order
price	string (decimal)	Execution price per share
shares	string (decimal)	Number of shares traded
buyerFee	string (decimal)	Fee charged to the buyer
sellerFee	string (decimal)	Fee charged to the seller
createdAt	string (ISO 8601)	When the trade was executed

Fee Calculation

Fees are calculated as a percentage of the trade value:

fee = shares * price * feePercent / 100

The default trading fee is 2.0%, applied to both buyer and seller. This is configurable via the DEFAULT_TRADING_FEE_PERCENT environment variable.

Example: A trade of 100 shares at $0.65 with a 2% fee:

• Trade value: 100 * 0.65 = $65.00
• Buyer fee: 65.00 * 0.02 = $1.30
• Seller fee: 65.00 * 0.02 = $1.30

Understanding Trade Data

• Trades reference both the buy and sell order IDs so you can trace which orders were matched
• Your operator will appear as either buyerOperatorId or sellerOperatorId depending on the order side
• The price is always the execution price (which may differ from the order's limit price)
• Trades are immutable — once created, they cannot be modified or deleted