Skip to main content
GET
/
data
/
trades
List trades
curl --request GET \
  --url https://clob.forka.st/data/trades \
  --header 'FORKAST_ADDRESS: <forkast_address>' \
  --header 'FORKAST_API_KEY: <forkast_api_key>' \
  --header 'FORKAST_PASSPHRASE: <forkast_passphrase>' \
  --header 'FORKAST_SIGNATURE: <forkast_signature>' \
  --header 'FORKAST_TIMESTAMP: <forkast_timestamp>'
[
  {
    "id": "01J9PQTW6J5N5R0A6VY3T3V9RJ",
    "taker_order_id": "01J9PQSZ4RZ1T2J5Q4K2H9V4PQ",
    "market": "0x9febb3d92e347a0990353d363df23878",
    "asset_id": "0x34b62d0ca7bf5d069a0f3c8ec7d8f9a1",
    "side": "buy",
    "size": "125.000000",
    "fee_rate_bps": "150",
    "price": "0.480000",
    "status": "CONFIRMED",
    "match_time": "2024-09-16T14:32:18.421Z",
    "last_update": "2024-09-16T14:32:18.421Z",
    "outcome": "",
    "maker_address": "0x7e6E0dC2a42A7236bF8A8E3F582F9F7a23d94e7A",
    "owner": "0x7e6E0dC2a42A7236bF8A8E3F582F9F7a23d94e7A",
    "transaction_hash": null,
    "bucket_index": 0,
    "maker_orders": [
      {
        "order_id": "01J9PPY3V9KF6R2B5XQ7C1H4LD",
        "maker_address": "0x67C0e7cA253d5437a6982a972C8f33008aB5E3C2",
        "owner": "7f50e965-32ff-4a86-a3f4-19c2af513d42",
        "matched_amount": "125.000000",
        "fee_rate_bps": "75",
        "price": "0.480000",
        "asset_id": "0x34b62d0ca7bf5d069a0f3c8ec7d8f9a1",
        "outcome": "",
        "side": "sell"
      }
    ],
    "type": "TAKER"
  },
  {
    "id": "01J9PQWS1H2D3K4L5M6N7P8Q9R",
    "taker_order_id": "01J9PQSZ4RZ1T2J5Q4K2H9V4PQ",
    "market": "0x9febb3d92e347a0990353d363df23878",
    "asset_id": "0x34b62d0ca7bf5d069a0f3c8ec7d8f9a1",
    "side": "buy",
    "size": "75.000000",
    "fee_rate_bps": "150",
    "price": "0.482500",
    "status": "CONFIRMED",
    "match_time": "2024-09-16T13:55:42.117Z",
    "last_update": "2024-09-16T13:55:42.117Z",
    "outcome": "",
    "maker_address": "0x7e6E0dC2a42A7236bF8A8E3F582F9F7a23d94e7A",
    "owner": "0x7e6E0dC2a42A7236bF8A8E3F582F9F7a23d94e7A",
    "transaction_hash": null,
    "bucket_index": 0,
    "maker_orders": [
      {
        "order_id": "01J9PPK27MQ4V6C8E0A2B4D5F6",
        "maker_address": "0x3D81a7Bf64aF98C20a05F7333b6AA6b6C8cD92e1",
        "owner": "3cc1d987-4af1-4810-b0fd-4af78a5f8bd9",
        "matched_amount": "75.000000",
        "fee_rate_bps": "60",
        "price": "0.482500",
        "asset_id": "0x34b62d0ca7bf5d069a0f3c8ec7d8f9a1",
        "outcome": "",
        "side": "sell"
      }
    ],
    "type": "TAKER"
  }
]
Fetch trades where your authenticated account participated as the taker or as one of the matched makers.
Provide the L2 headers (FORKAST_ADDRESS, FORKAST_SIGNATURE, FORKAST_TIMESTAMP, FORKAST_API_KEY, FORKAST_PASSPHRASE). The endpoint only returns fills linked to that credential set.

​
Query parameters

ParameterTypeRequiredDescription
idstringNoTrade ULID (case-insensitive). Returns at most one entry.
takerstringNoFilter by taker wallet address.
makerstringNoFilter by maker wallet address.
marketstringNoConditionID (market identifier).
beforestringNoUnix timestamp (seconds); include trades strictly before this instant.
afterstringNoUnix timestamp (seconds); include trades strictly after this instant.
Filters can be combined. Omitted parameters are ignored, and empty strings are treated as if the filter were not supplied.

​
Response fields

Each element in the returned array contains:
FieldTypeDescription
idstringTrade ULID.
taker_order_idstringULID for the market order that initiated the trade.
marketstringCondition (market) ULID.
asset_idstringToken ID tied to the taker order.
sidestringbuy or sell, from the taker’s perspective.
sizestringExecuted quantity (decimal string).
fee_rate_bpsstringTaker fee rate in basis points.
pricestringExecuted price (decimal string between 0 and 1).
statusstringCurrently always CONFIRMED.
match_timestringISO-8601 timestamp for when the trade matched.
last_updatestringISO-8601 timestamp of the latest status update (same as match_time for now).
outcomestringPlaceholder outcome label; currently empty.
maker_addressstringWallet that funded the taker order.
ownerstringAPI key owner for the taker order (falls back to the taker wallet).
transaction_hashstring|nullNot populated yet; reserved for on-chain settlement hashes.
bucket_indexintegerAlways 0 until bucketed settlements are exposed.
maker_ordersarrayMaker orders that filled the trade.
typestringTAKER if your account submitted the market order, otherwise MAKER.

​
maker_orders entries

FieldTypeDescription
order_idstringMaker order ULID.
maker_addressstringMaker wallet address.
ownerstringAPI key owner for the maker order (falls back to the maker wallet).
matched_amountstringQuantity filled from the maker order (decimal string).
fee_rate_bpsstringMaker fee rate in basis points.
pricestringMaker order price.
asset_idstringToken ID associated with the maker order.
outcomestringPlaceholder outcome label; currently empty.
sidestringMaker order side (buy or sell).

​
Known gaps

  • status is fixed to CONFIRMED until lifecycle updates propagate through the API.
  • transaction_hash, bucket_index, and outcome are placeholder fields for future on-chain and bucketed settlement support.
  • Each trade currently exposes a single maker fill; multi-fill buckets will surface once the API publishes them.

Headers

​
FORKAST_ADDRESS
string
required

Wallet address associated with the L2 credentials.

​
FORKAST_SIGNATURE
string
required

EIP-712 signature authorizing the request.

​
FORKAST_TIMESTAMP
string
required

Unix timestamp (seconds) matching the signed payload.

​
FORKAST_API_KEY
string
required

API key identifier issued via L2 credential flow.

​
FORKAST_PASSPHRASE
string
required

64-character passphrase paired with the API key.

Query Parameters

​
id
string

Trade ULID to fetch (case-insensitive).

​
taker
string

Filter by taker wallet address.

​
maker
string

Filter by maker wallet address.

​
market
string

ConditionID (market) to filter on.

​
before
string

Unix timestamp (seconds); include trades strictly before this instant.

​
after
string

Unix timestamp (seconds); include trades strictly after this instant.

Response

Trades matching the supplied filters.

​
id
string
required

Trade ULID.

​
taker_order_id
string
required

Market order ULID that initiated the trade.

​
market
string
required

Condition (market) ULID.

​
asset_id
string
required

Token ID associated with the taker order.

​
side
string
required

Taker side (buy or sell).

​
size
string
required

Executed quantity (decimal string).

​
fee_rate_bps
string
required

Taker fee rate in basis points.

​
price
string
required

Executed price (decimal string between 0 and 1).

​
status
string
required

Trade status (currently always CONFIRMED).

​
match_time
string<date-time>
required

Timestamp when the trade matched.

​
last_update
string<date-time>
required

Timestamp of the last status update.

​
outcome
string
required

Human-readable outcome label (placeholder).

​
maker_address
string
required

Wallet that funded the taker order.

​
owner
string
required

Taker account identifier.

​
transaction_hash
string | null
required

Reserved for on-chain settlement hash (currently null).

​
bucket_index
integer
required

Settlement bucket index (currently 0).

​
maker_orders
object[]
required

Maker orders that filled the trade.

​
type
string
required

TAKER when the authenticated account submitted the market order, otherwise MAKER.