# API

Public reference for integrating Pascal's REST and WebSocket APIs.

All write requests are signed. Read requests are unauthenticated. The Write and
Read APIs use distinct base URLs; see [Base URLs](#base-urls).



## General Information

### Base URLs

Use the production URLs for live trading:

| Service | URL |
|---|---|
| Web | `https://app.pascal.trade` |
| Write API | `https://trade.pascal.trade` |
| Order Entry WebSocket | `wss://trade.pascal.trade/ws` |
| REST Read API | `https://data.pascal.trade` |
| Market Data WebSocket | `wss://data.pascal.trade/ws` |

### Geography

The Pascal matching engine is located in AWS ap-northeast-1.

### Rate Limits

Rate limits may change. Clients must handle HTTP 429 responses.

Current rate limit: 100 requests per second. You can batch up to 50 orders per request.

### Authentication and Request Authorization

#### Signing Keys

Each Solana wallet address owns one Pascal account. Pascal separates account
ownership from trading authorization, so certain operations (moving funds,
approving trading keys) require wallet signatures, while order placement and
cancellation are signed by separate trading keys.

This allows accounts to use higher security custody, like hardware or MPC wallets, without
prohibiting the use of hot keys for trading.

| Key | Use | Used by |
|---|---|---|
| Wallet key | Custody, withdrawals, and trading-key lifecycle | Create/revoke trading keys, withdraw collateral, register deposit addresses |
| Trading key | Order placement and cancellation | Place and cancel orders |

In every signed request, `owner` is the wallet public key, also used as the
Solana address, and `signer` is the key that produced the Ed25519 signature.
Wallet-signed requests require `signer == owner`.

#### Request Authorization

Every signed request carries a `RequestAuth` object with replay and staleness
protection fields `client_ts_ms` and `recv_window_ms`:

##### RequestAuth

Request authentication metadata used to validate client requests.

| Field | Type | Description |
|---|---|---|
| `client_ts_ms` | u64 string | Client timestamp in milliseconds since the Unix epoch. Used with `recv_window_ms` for replay and staleness checks. |
| `recv_window_ms` | u32 string | Maximum age of the request in milliseconds. The server accepts the request when `server_time_ms - client_ts_ms <= recv_window_ms`. |
| `owner` | base58 string | Account owner's wallet public key (Solana address). |
| `signer` | base58 string | Public key that signed this request. Wallet-signed requests require `signer == owner`; trading-key requests use a registered trading key. |
| `signature` | base58 string | Ed25519 signature over the signed payload bytes for this request. |


`recv_window_ms` may be at most 60,000ms (1 minute).

See [Request Signing](request-signing.txt#request-signing) for constructing the exact payloads
to sign over.

> [info!] The easiest way to start signing requests is with [github.com/pascal-research-inc/pascal-python-quickstart](https://github.com/Pascal-Research-Inc/pascal-python-quickstart#quickstart)

### Generate A Trading Key In The Browser

For most users the easiest way to get a trading key is through the Pascal web
app. The web app handles wallet prompts, permit construction, and key generation.

1. Open the Pascal web app, for example [https://app.pascal.trade](https://app.pascal.trade), and log
   in with the wallet of your choice. To keep wallet keys off the computer, use
   a hardware wallet or MPC solution.
2. Click your account image in the upper right, then **Trading Keys > Create Key**.
3. Give the key a name and save the private key somewhere secure.

Alternatively, to generate and assign a trading key programmatically, call
[Create A Trading Key](#create-a-trading-key) directly with an Ed25519 public key
and a wallet-signed `create_trading_key` permit.

### Response Envelopes

All REST API responses are wrapped in:

| Field | Type | Description |
|---|---|---|
| `status` | string enum | `success` or `error` |
| `data` | object | Endpoint response payload on `success`, otherwise error object. |
| `seq` | u64 string | (Optional) Matching engine sequence number. Not present if the request is rejected before reaching the matching engine, for example due to invalid request data. |
| `state_time_ms` | u64 string | (Optional) Matching engine timestamp as of the last matching round. Not present if the request is rejected before reaching the matching engine, for example due to invalid request data. |
| `server_time_ms` | u64 string | API server timestamp when this result was produced. Requests in a batch request can resolve at different times, so items in one response may carry different timestamps. |
| `server_receive_time_ms` | u64 string | (Optional) API server timestamp when the HTTP request is received. Present on write endpoint responses, including rejections and timeouts. Not present on read endpoint responses or WebSocket messages. |


Request-validation and rate-limit error responses may omit `server_time_ms`.

Error data is an object with fields:

| Field | Type | Description |
|---|---|---|
| `code` | [ApiErrorCode](#apierrorcode) | Stable, machine-readable error code. |
| `message` | string | Human-readable error message. May evolve over time. For debugging and display only. |


Batch endpoints normally return an array of envelopes, one per submitted request, in
the same order as the request batch. Request-level errors, including rate limits,
return one error envelope.

Batch endpoints return HTTP 200 if *any* request in the batch succeeds. Inspect
each item's `status` to determine which requests succeeded or failed. Other endpoints
return 200 only on `{"status": "success"}`.

**Success envelope**

```json
{
  "status": "success",
  "data": {
    "server_time_ms": "1731536000123"
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

**Error envelope**

```json
{
  "status": "error",
  "data": {
    "code": "INVALID_REQUEST",
    "message": "count_back must be positive"
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

**Batch response envelope**

```json
[
  {
    "status": "success",
    "data": {
      "id": "987654321",
      "client_order_id": "42",
      "symbol": "SIM_EVENT_1.MARKET_1",
      "side": "BID",
      "price": "0.550000",
      "size_original": "10",
      "size_remaining": "0",
      "size_filled": "3",
      "notional_filled": "1.650000",
      "tif": "GTC",
      "type": "LIMIT",
      "post_only": false,
      "reduce_only": false,
      "seq": "67880",
      "update_seq": "67891",
      "place_ts_ms": "1731536000050",
      "update_ts_ms": "1731536000050"
    },
    "seq": "67891",
    "state_time_ms": "1731536000050",
    "server_time_ms": "1731536000123"
  },
  {
    "status": "error",
    "data": {
      "code": "ORDER_NOT_FOUND",
      "message": "client_order_id 43 is not an open order"
    },
    "seq": "67891",
    "state_time_ms": "1731536000050",
    "server_time_ms": "1731536000123"
  }
]
```

### Pagination

Paginated endpoints accept an optional `limit` and at most one starting point: `before_cursor`
or `at_or_before_seq`.

- `at_or_before_seq` allows starting pagination at a sequence number. Continue paginating using the cursor.
- `before_cursor` is the cursor returned from a previous page.
- `limit` uses min 1, default 100, max 500.

Treat cursor values as opaque. The internal format may change without notice;
clients should only round-trip `next_cursor` back into `before_cursor`.

Paginated responses wrap the page in the standard [response envelope](#response-envelopes).
Its `data` object contains:

| Field | Type | Description |
|---|---|---|
| `items` | array | Result page items. The item schema is shown under each paginated endpoint. |
| `next_cursor` | string | (Optional) Cursor for the next page of results. Omitted on the last page. |

The envelope `seq` and `state_time_ms` indicate the freshness of the historical data.

If the requested pagination boundary is beyond indexed history, the API returns
HTTP 503 with `code: "HISTORY_NOT_READY"`. Retry the same boundary after a delay.

See the historical [Trades](#trades) query for an example.

### JSON Conventions

| Shape | Encoding |
|---|---|
| Decimal prices, USD amounts, rates, and fees | String with 6 fractional digits unless the field description says otherwise. Price fields stay within 0.000000 to 1.000000. |
| Contract sizes, sequence numbers, ids, timestamps, and cursors | Serialized as strings |
| Timestamps | Unix milliseconds. |
| Solana addresses, public keys, and Ed25519 signatures | Base58 strings. |
| Market symbols | Uppercase string identifiers. |

### Sequence Numbers

Responses to API calls that read or update exchange state include a `seq` number.

The `seq` is a global counter that increments on every exchange state change.
It only increases. **Note: it is not a per-connection message counter.**

You can compare `seq` values across REST, WebSocket, and historical APIs to tell
which state is newer. For example:

- Order responses include the `seq` at which the order was placed.
- REST account and order book snapshots include the snapshot's `seq` in the
  response envelope.
- WebSocket messages include the `seq` of the state that produced the update.
- Historical data queries include the highest `seq` of indexed state.
  For example, the historical trades response is guaranteed to include every
  trade where `trade.seq <= envelope.seq`.

For example, after placing an order, suppose the order response has `seq = o`.
Then a WebSocket book update arrives with `seq = w`:

- If `w < o`, the update is from state before your order was placed.
- If `w = o`, the update is from the same state transition as your order.
- If `w > o`, the update is from state after your order was placed.

Individual WebSocket channels can carry non-contiguous `seq` values because
multiple state changes occur in each [matching round](general.txt#matching-rounds-and-priority)
and not every global state change affects each specific WebSocket channel.

## Write Endpoints

### Place And Replace Orders

`POST <write_base_url>/api/v1/orders`

Places or amends one or more orders. Each order is independently signed and independently
succeeds or fails. The maximum batch size is 50.

**Request Body**

Request bodies are JSON arrays. Every element is a JSON object:

#### PlaceOrderRequest

Client sends this request to the API to place an order.

| Field | Type | Description |
|---|---|---|
| `client_order_id` | u64 string | Client-assigned order identifier. Must be unique across open orders for the same account. Must be `< 2^64 - 1`. |
| `replace_client_order_id` | u64 string | (Optional) If present, the order with `replace_client_order_id` will be cancelled and replaced atomically with this new order. If the replacement only reduces remaining size, the order preserves the existing queue position. |
| `symbol` | string ([Symbol](#market-symbols)) | Symbol for the market to trade. |
| `side` | string enum: `"BID"`, `"ASK"` | Whether to buy (`BID`) or sell (`ASK`). |
| `price` | decimal string, 6 d.p. | Limit price in dollars. |
| `size` | u64 string | Order size in contracts. |
| `tif` | [TimeInForce](#timeinforce) | (Optional) The order's [TimeInForce](#timeinforce) policy. Defaults to `GTC`. |
| `post_only` | boolean | (Optional) If true, the order can only match as a maker. If it would cross immediately, the order is rejected. |
| `reduce_only` | boolean | (Optional) If true, the order can only reduce exposure and never increase it. |
| `allow_missing_replace` | boolean | (Optional) If true, the order is placed even if `replace_client_order_id` is not found. Requires `replace_client_order_id`. Incompatible with `replace_with_open_size`. |
| `replace_with_open_size` | boolean | (Optional) If true, the replacement does not alter the open order's size. Set the request `size` equal to the open size you think the order has and sign over it. When this request lands, the matching engine will inspect the size remaining for `replace_client_order_id`, and set the new order's size equal to that. Incompatible with `allow_missing_replace`. |
| `expires_ts_ms` | u64 string | (Optional) Expiration timestamp, required for `GTT` orders and forbidden otherwise. |
| `builder_info` | [BuilderInfo](#builderinfo) | (Optional) Builder attribution and fee settings, signed into the order permit. A present value must name a registered builder other than the order's own account; omitting the field is the only no-builder form. Rejected with `BUILDER_INVALID` for an unknown or self-named builder, `BUILDER_FEE_RATE_INVALID` for a fee rate above `BUILDER_FEE_RATE_CAP`, and `BUILDER_COLLATERAL_BELOW_MINIMUM` when the builder does not meet the minimum free collateral. |
| `auth` | [RequestAuth](#requestauth) | Signed request authentication metadata. |


`tif` (time in force) values:

#### TimeInForce

Time in force for an order.

| Value | Description |
|---|---|
| `"GTC"` | Good 'til canceled: the order rests on the book until it is fully filled or explicitly canceled. |
| `"GTT"` | Good 'til time: like GTC, but the order is automatically canceled once `expires_ts_ms` passes. |
| `"IOC"` | Immediate or cancel: fills against resting orders immediately; any unfilled remainder is canceled instead of resting on the book. |


`builder_info`, when present, is a JSON object (see
[Builder Codes](general.txt#builder-codes)):

#### BuilderInfo

Builder public key and fee rate for one order, signed into the order permit.

| Field | Type | Description |
|---|---|---|
| `builder_pubkey` | base58 string | Registered builder account credited for this order. |
| `builder_fee_rate` | decimal string, 6 d.p. | Builder fee rate. Each fill pays the builder `size × price × (1 − price) × builder_fee_rate`, rounded toward zero. |


**JSON Response Payload**

Batch responses are JSON arrays of responses. On success, each response's
`data` object has these fields:

| Field | Type | Description |
|---|---|---|
| `order` | [OrderMsg](#ordermsg) | The state of the order after placement, including any fills that occurred immediately. |
| `fills` | array of [FillMsg](#fillmsg) | Fills that occurred during the placement of the order. |


`order` object schema:

#### OrderMsg

Order message for API responses.

| Field | Type | Description |
|---|---|---|
| `id` | u64 string | The order's unique identifier, assigned by the exchange. |
| `client_order_id` | u64 string | Client ID for the order. |
| `replace_client_order_id` | u64 string | (Optional) Present when this order was placed as a replacement. |
| `symbol` | string ([Symbol](#market-symbols)) | The symbol of the market being traded. |
| `side` | string enum: `"BID"`, `"ASK"` | The side of the order. |
| `price` | decimal string, 6 d.p. | The limit price of the order in dollars. |
| `size_original` | u64 string | The order size in contracts at placement time. |
| `size_remaining` | u64 string | Remaining open quantity, matching FIX `LeavesQty` semantics. The order is closed when this is zero, whether it filled completely, was canceled, expired, or was resolved by the matching engine. Note that an order's size can be reduced by the matching engine due to `reduce_only` or self trade prevention. Use `size_filled` to determine filled size, not `size_remaining`. |
| `size_filled` | u64 string | The cumulative size of the order that has been filled. |
| `notional_filled` | decimal string, 6 d.p. | The cumulative sum of `price * size` for fills to this order. Divide by `size_filled` to get the average fill price. |
| `tif` | [TimeInForce](#timeinforce) | The order's [TimeInForce](#timeinforce). |
| `type` | string enum: `"LIMIT"`, `"MARKET"` | Order display type. `LIMIT` is a standard limit order. `MARKET` requires `IOC` and executes only at its specified limit price or better. |
| `post_only` | boolean | If true, the order is only allowed to fill as a maker. |
| `reduce_only` | boolean | If true, the order is only allowed to reduce existing exposure and never increase it. |
| `expires_ts_ms` | u64 string | (Optional) The expiration timestamp of the order in milliseconds since the Unix epoch, omitted if the order is not `GTT`. |
| `builder_pubkey` | base58 string | (Optional) Builder named by this order, omitted when the order has no builder. |
| `builder_fee_rate` | decimal string, 6 d.p. | (Optional) Builder fee rate signed into this order, omitted when the order has no builder. |
| `seq` | u64 string | The sequence number when this order was placed. |
| `update_seq` | u64 string | The sequence number when this order last changed. |
| `place_ts_ms` | u64 string | The timestamp the order was placed at. |
| `update_ts_ms` | u64 string | The timestamp when this order last changed. |


Every element in `fills` is a JSON object:

#### FillMsg

Fill message for API responses.

| Field | Type | Description |
|---|---|---|
| `trade_id` | u64 string | Unique ID for this trade. |
| `symbol` | string ([Symbol](#market-symbols)) | Symbol for the market being traded. |
| `side` | string enum: `"BID"`, `"ASK"` | Side of the order that was filled. |
| `fill_price` | decimal string, 6 d.p. | Execution price in dollars. |
| `fill_size` | u64 string | Filled quantity in contracts. |
| `liquidity` | string enum: `"TAKER"`, `"MAKER"` | Whether this fill removed liquidity (`TAKER`) or provided it (`MAKER`). |
| `order_id` | u64 string | Exchange ID of the order that was filled. |
| `client_order_id` | u64 string | Client ID of the order that was filled. |
| `fee_usd` | signed decimal string, 6 d.p. | Venue fee charged for this fill, excluding builder fees. Positive values are fees paid; negative values are rebates. |
| `collateral_change_usd` | signed decimal string, 6 d.p. | This fill side's collateral change: position collateral change minus the side's fees. Credits the account receives from the same trade (builder fees received or a referral reward) are separate and not included. |
| `position_size_prev` | i64 string | Signed position size in this market immediately before the fill. |
| `realized_pnl_usd` | signed decimal string, 6 d.p. | Realized PnL attributed to this fill, excluding fees. |
| `position_open_seq` | u64 string | (Optional) Opening sequence of the position instance associated with this fill. On a flip, this identifies the position closed by the fill rather than the residual position it opens. |
| `position_open_ts_ms` | u64 string | (Optional) Opening timestamp, in milliseconds since the Unix epoch, of the position instance associated with this fill. On a flip, this identifies the position closed by the fill rather than the residual position it opens. |
| `builder_pubkey` | base58 string | (Optional) Builder named by the filled order, omitted when the order has no builder. |
| `builder_fee_paid_usd` | decimal string, 6 d.p. | (Optional) Builder fee paid to the builder for this fill, included in `collateral_change_usd`; omitted when the order has no builder. |
| `seq` | u64 string | Matching engine sequence number when this fill occurred. |
| `trade_ts_ms` | u64 string | Timestamp when this fill occurred, in milliseconds since the Unix epoch. |


**Example request**

```bash
curl -X POST https://trade.pascal.trade/api/v1/orders \
  -H 'Content-Type: application/json' \
  --data @- <<'EOF'
[
  {
    "client_order_id": "42",
    "symbol": "SIM_EVENT_1.MARKET_1",
    "side": "BID",
    "price": "0.550000",
    "size": "10",
    "auth": {
      "client_ts_ms": "1731536000000",
      "recv_window_ms": "5000",
      "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
      "signer": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
      "signature": "2rUctQ9bFbuQaUxbXDGRtGm4LMj3GdbYWAW6pjrznAsLvpdH8Eqyx3LgsFx3YzV9cvMfw1ND5T5nChUQZZJ7jEad"
    }
  }
]
EOF
```

**Example response**

```json
[
  {
    "status": "success",
    "data": {
      "order": {
        "id": "987654321",
        "client_order_id": "42",
        "symbol": "SIM_EVENT_1.MARKET_1",
        "side": "BID",
        "price": "0.550000",
        "size_original": "10",
        "size_remaining": "7",
        "size_filled": "3",
        "notional_filled": "1.650000",
        "tif": "GTC",
        "type": "LIMIT",
        "post_only": false,
        "reduce_only": false,
        "seq": "67880",
        "update_seq": "67891",
        "place_ts_ms": "1731536000050",
        "update_ts_ms": "1731536000050"
      },
      "fills": [
        {
          "trade_id": "555001",
          "symbol": "SIM_EVENT_1.MARKET_1",
          "side": "BID",
          "fill_price": "0.550000",
          "fill_size": "3",
          "liquidity": "TAKER",
          "order_id": "987654321",
          "client_order_id": "42",
          "fee_usd": "0.000742",
          "collateral_change_usd": "-1.650742",
          "position_size_prev": "0",
          "realized_pnl_usd": "0.000000",
          "seq": "67891",
          "trade_ts_ms": "1731536000050"
        }
      ]
    },
    "seq": "67891",
    "state_time_ms": "1731536000050",
    "server_time_ms": "1731536000123"
  }
]
```

### Cancel Orders

`POST <write_base_url>/api/v1/cancels`

Cancels one or more orders by client order id or exchange order id. Each cancel is
independently signed and independently succeeds or fails. The maximum batch size is
50.
Canceling by client order id and canceling by exchange order id have equivalent
performance.

**Request Body**

Request bodies are JSON arrays. Every element is a JSON object:

#### CancelOrderRequest

Client sends this request to the API to cancel an order.

| Field | Type | Description |
|---|---|---|
| `client_order_id` | u64 string | (One of) Client ID of the order to cancel. |
| `order_id` | u64 string | (One of) Exchange ID of the order to cancel. |
| `auth` | [RequestAuth](#requestauth) | Signed request authentication metadata. |


**JSON Response Payload**

Batch responses are JSON arrays of write envelopes. On success, each envelope's
`data` object is an [OrderMsg](#ordermsg) with the cancelled order's final state.

**Example request**

```bash
curl -X POST https://trade.pascal.trade/api/v1/cancels \
  -H 'Content-Type: application/json' \
  --data @- <<'EOF'
[
  {
    "client_order_id": "42",
    "auth": {
      "client_ts_ms": "1731536000000",
      "recv_window_ms": "5000",
      "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
      "signer": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
      "signature": "591YziUjZzro24mamxgRrSDdYD71NpsDBmU4UGSyrBYbFiWzYaLjR9he1P5DP8djMKMJzHTsZzwRAagvLqgtiXnc"
    }
  },
  {
    "client_order_id": "43",
    "auth": {
      "client_ts_ms": "1731536000000",
      "recv_window_ms": "5000",
      "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
      "signer": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
      "signature": "3wFZKJWKA92W6iPszoKQccQmrVEfd6hU68HY6mqWYKEH8yFKQEFRJs1tKmrGDy1PMd3wWwcdcYSVoTgrW5KSnP3f"
    }
  }
]
EOF
```

**Example response**

```json
[
  {
    "status": "success",
    "data": {
      "id": "987654321",
      "client_order_id": "42",
      "symbol": "SIM_EVENT_1.MARKET_1",
      "side": "BID",
      "price": "0.550000",
      "size_original": "10",
      "size_remaining": "0",
      "size_filled": "3",
      "notional_filled": "1.650000",
      "tif": "GTC",
      "type": "LIMIT",
      "post_only": false,
      "reduce_only": false,
      "seq": "67880",
      "update_seq": "67891",
      "place_ts_ms": "1731536000050",
      "update_ts_ms": "1731536000050"
    },
    "seq": "67891",
    "state_time_ms": "1731536000050",
    "server_time_ms": "1731536000123"
  },
  {
    "status": "success",
    "data": {
      "id": "987654322",
      "client_order_id": "43",
      "symbol": "SIM_EVENT_1.MARKET_1",
      "side": "BID",
      "price": "0.550000",
      "size_original": "10",
      "size_remaining": "0",
      "size_filled": "3",
      "notional_filled": "1.650000",
      "tif": "GTC",
      "type": "LIMIT",
      "post_only": false,
      "reduce_only": false,
      "seq": "67880",
      "update_seq": "67891",
      "place_ts_ms": "1731536000050",
      "update_ts_ms": "1731536000050"
    },
    "seq": "67891",
    "state_time_ms": "1731536000050",
    "server_time_ms": "1731536000123"
  }
]
```

### Create A Trading Key

`POST <write_base_url>/api/v1/trading-keys`

Authorizes a trading key for an account. This request is wallet-signed.

Trading key names may be at most 16 bytes long, and
their expiration timestamps may be no more than
31,536,000,000ms (365 days) in the future. An account may store
at most 10 unrevoked trading keys at a time.
Expired keys count against this limit until revoked.


**Request Body**

| Field | Type | Description |
|---|---|---|
| `trading_key` | base58 string | Ed25519 public key to authorize for trading on this account. |
| `name` | string | Human-readable label for this trading key. **This name is public onchain.** |
| `expiration_ts_ms` | u64 string | Timestamp when this trading key expires, in milliseconds since the Unix epoch. |
| `auth` | [RequestAuth](#requestauth) | Signed request authentication metadata. |


**JSON Response Payload**

On success, the response envelope's `data` object has these fields:

#### TradingKeyMsg

Trading key entry in API responses.

| Field | Type | Description |
|---|---|---|
| `trading_key` | base58 string | Ed25519 public key authorized to sign trading requests for this account. |
| `name` | string | Human-readable label for this trading key. **This name is public onchain.** |
| `expiration_ts_ms` | u64 string | Timestamp when this trading key expires, in milliseconds since the Unix epoch. |
| `open_order_count` | u64 string | Number of this account's currently open orders placed using this trading key. |


**Example request**

```bash
curl -X POST https://trade.pascal.trade/api/v1/trading-keys \
  -H 'Content-Type: application/json' \
  --data @- <<'EOF'
{
  "trading_key": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
  "name": "api-doc-key",
  "expiration_ts_ms": "1732140800000",
  "auth": {
    "client_ts_ms": "1731536000000",
    "recv_window_ms": "5000",
    "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "signer": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "signature": "kyc2KdqPTeEWqoK3pXR2rgPUiK4zXg9QdQffPUWk8eALpFy7uaHBEsASt7RQyVzDeubHVsPqQAHXrt8m8KZ78Ep"
  }
}
EOF
```

**Example response**

```json
{
  "status": "success",
  "data": {
    "trading_key": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
    "name": "api-doc-key",
    "expiration_ts_ms": "1732140800000",
    "open_order_count": "0"
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Revoke A Trading Key

`POST <write_base_url>/api/v1/trading-key-revocations`

Revokes a previously authorized trading key. This request is wallet-signed.

**Request Body**

| Field | Type | Description |
|---|---|---|
| `trading_key` | base58 string | Ed25519 public key of the trading key to revoke. |
| `auth` | [RequestAuth](#requestauth) | Signed request authentication metadata. |


**JSON Response Payload**

On success, the response envelope's `data` object has these fields:

| Field | Type | Description |
|---|---|---|
| `trading_key` | base58 string | Ed25519 public key of the revoked trading key. |


**Example request**

```bash
curl -X POST https://trade.pascal.trade/api/v1/trading-key-revocations \
  -H 'Content-Type: application/json' \
  --data @- <<'EOF'
{
  "trading_key": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
  "auth": {
    "client_ts_ms": "1731536000000",
    "recv_window_ms": "5000",
    "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "signer": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "signature": "3muKct6upyRNAr1CPdYcxQGCojpuB4gaEnWvbNwEBJ6rrKaThRZrKY56rpYbFEsGUZqJ4iCTJqYrPuxfGYVzXQX3"
  }
}
EOF
```

**Example response**

```json
{
  "status": "success",
  "data": {
    "trading_key": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1"
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Withdraw Collateral

`POST <write_base_url>/api/v1/withdrawals`

Requests withdrawal of collateral to a destination token account. This request is
wallet-signed.

Clients do not send a fee field. `amount` is the gross amount debited from the
account; the exchange sends `amount` minus the current signed withdrawal fee to
`destination_token_account`. The current signed withdrawal fee is
$0.50.

**Destination address**

Derive the `destination_token_account` [associated token account (ATA)](https://solana.com/docs/tokens/basics/create-token-account#what-is-an-associated-token-account) with the standard
Solana formula: PDA seeds `[wallet, spl_token_program_id, usd_token_mint]` under the
Associated Token program.

**Request Body**

| Field | Type | Description |
|---|---|---|
| `amount` | decimal string, 6 d.p. | Amount of collateral to withdraw in USD. The exchange debits this amount from the account and sends `amount` minus the withdrawal fee to the destination. |
| `destination_authority` | base58 string | Solana wallet address that will receive the withdrawal. This is the address the user enters in a "withdraw to" field, not a token account address. |
| `destination_token_account` | base58 string | USD associated token account (ATA) for `destination_authority`. Must equal the ATA derived from `destination_authority` and the deployment's USD token mint. Clients derive this locally before signing because both fields are included in the signed withdrawal permit. |
| `auth` | [RequestAuth](#requestauth) | Signed request authentication metadata. |


**JSON Response Payload**

On success, the response envelope's `data` object has these fields:

| Field | Type | Description |
|---|---|---|
| `owner` | base58 string | Account owner's wallet public key (Solana address). |
| `amount` | decimal string, 6 d.p. | Amount of collateral withdrawn in USD. |
| `destination_authority` | base58 string | Solana wallet address that received the withdrawal. |
| `destination_token_account` | base58 string | USD associated token account (ATA) for `destination_authority` that received the withdrawal. |


**Example request**

```bash
curl -X POST https://trade.pascal.trade/api/v1/withdrawals \
  -H 'Content-Type: application/json' \
  --data @- <<'EOF'
{
  "amount": "25.000000",
  "destination_authority": "29d2S7vB453rNYFdR5Ycwt7y9haRT5fwVwL9zTmBhfV2",
  "destination_token_account": "3JF3sEqM796hk5WFqA6EtmEwJQ9quALszsfJyvXNQKy3",
  "auth": {
    "client_ts_ms": "1731536000000",
    "recv_window_ms": "5000",
    "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "signer": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "signature": "61YYUBk6BTXkfrksMbqDLUNxwo6jhMPqdP7fNnWjNF2FYvMDujTsaUxfCiRxXX72jxy4oLtt6AtLodCvjDi4XpDn"
  }
}
EOF
```

**Example response**

```json
{
  "status": "success",
  "data": {
    "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "amount": "25.000000",
    "destination_authority": "29d2S7vB453rNYFdR5Ycwt7y9haRT5fwVwL9zTmBhfV2",
    "destination_token_account": "3JF3sEqM796hk5WFqA6EtmEwJQ9quALszsfJyvXNQKy3"
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Register A Deposit Address

`POST <write_base_url>/api/v1/deposit-addresses`

Registers the account's deposit address for balance scanning. This request is wallet-signed.
A new account may include a referrer's `referral_code` to credit the referral. A registration
carrying a Referral Code succeeds only when attribution is created. If the code is unknown,
revoked, self-referring, or otherwise cannot resolve, the request fails with
`REFERRAL_CODE_INVALID`; the account remains unregistered and may retry with a corrected code or
without one. The Reward Owner can observe a successfully created Referral through their
[Referrals](#referrals) list.

> [info!]
> Pascal uses USDC as its sole collateral token. **Only send USDC to your deposit address.**

**Request Body**

| Field | Type | Description |
|---|---|---|
| `owner` | base58 string | Account owner's wallet public key (Solana address). |
| `referral_code` | string | (Optional) Referral code to credit for the referral, exactly as shared by the referrer. When supplied, registration succeeds only if referral attribution is created. An unknown, revoked, self-referring, or otherwise invalid code rejects registration with `REFERRAL_CODE_INVALID`; the account remains unregistered and can retry with a corrected code or without one. |
| `auth` | [RequestAuth](#requestauth) | Signed request authentication metadata. |


**JSON Response Payload**

| Field | Type | Description |
|---|---|---|
| `owner` | base58 string | The account owner. |
| `deposit_address` | base58 string | (Optional) The deposit address PDA corresponding to the account owner. Present only after the account has registered a deposit address, and immutable once set. |
| `registered` | boolean | Whether the deposit address is registered. |


**Example request**

```bash
curl -X POST https://trade.pascal.trade/api/v1/deposit-addresses \
  -H 'Content-Type: application/json' \
  --data @- <<'EOF'
{
  "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
  "referral_code": "k7wq2m4x",
  "auth": {
    "client_ts_ms": "1731536000000",
    "recv_window_ms": "5000",
    "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "signer": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "signature": "2GVZuf1birCpfr6DKbu1ALSxRTpVnzFAa6oYqnEsnDUB2TFqeYTsKEZrCxNzATyCZbEaLW7koZJPRh9euhYiLtm4"
  }
}
EOF
```

**Example response**

```json
{
  "status": "success",
  "data": {
    "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "deposit_address": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "registered": true
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Generate A Referral Code

`POST <write_base_url>/api/v1/referral-codes`

Creates the owner's reusable referral code. This request is signed by an active trading key.
Each owner can generate one code, and generation requires a deposited account. Use
[Referrals](#referrals) for the owner's current code and the `can_generate_referral_code` flag.

A new user referred with this code submits it as `referral_code` in
[Register A Deposit Address](#register-a-deposit-address), which creates a Referral under the
[Referral Program](general.txt#referral-program).

**Request Body**

| Field | Type | Description |
|---|---|---|
| `auth` | [RequestAuth](#requestauth) | Trading-key-signed request authentication metadata. |


**JSON Response Payload**

On success, the response envelope's `data` object has these fields:

| Field | Type | Description |
|---|---|---|
| `generated_referral_code` | string | The owner's reusable referral code. |


**Example request**

```bash
curl -X POST https://trade.pascal.trade/api/v1/referral-codes \
  -H 'Content-Type: application/json' \
  --data @- <<'EOF'
{
  "auth": {
    "client_ts_ms": "1731536000000",
    "recv_window_ms": "5000",
    "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "signer": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
    "signature": "4UpZqQfCNDbj3NEnkkRUQsW5USTTcv7JekvPWyHsEC2ifcc3R8PwEVd5xVWZuSNacyNHrZg29ZqPeUME3GWGpnCN"
  }
}
EOF
```

**Example response**

```json
{
  "status": "success",
  "data": {
    "generated_referral_code": "k7wq2m4x"
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Claim A Custom Referral Code

`POST <write_base_url>/api/v1/referral-codes/custom`

Claims the owner's one-time Custom Referral Code. This request is signed by an active trading
key, requires a deposited account, and succeeds at most once per owner. Use
[Referrals](#referrals) for the owner's current code and `can_claim_custom_referral_code`.

The code must contain 6–20 lowercase ASCII letters or digits and is not normalized by the server.
Four- and five-character values fail with `referral_code_too_short`. Values shorter than four
characters or otherwise outside the Referral Code format fail request parsing. Codes that are
occupied or fail content policy fail with `referral_code_unavailable`.

**Request Body**

| Field | Type | Description |
|---|---|---|
| `referral_code` | string | Exact owner-chosen code: 6–20 lowercase ASCII letters or digits. The exchange does not normalize this value. |
| `auth` | [RequestAuth](#requestauth) | Trading-key-signed request authentication metadata. |


**JSON Response Payload**

On success, the response envelope's `data` object has these fields:

| Field | Type | Description |
|---|---|---|
| `custom_referral_code` | string | The owner's newly claimed Custom Referral Code. |


**Example request**

```bash
curl -X POST https://trade.pascal.trade/api/v1/referral-codes/custom \
  -H 'Content-Type: application/json' \
  --data @- <<'EOF'
{
  "referral_code": "trader1",
  "auth": {
    "client_ts_ms": "1731536000000",
    "recv_window_ms": "5000",
    "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "signer": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
    "signature": "26FzDQPEDR6u7rKhkaEEJL1YSyKpbUCCibQtQxkDfEfEjyAsJu17X5p8TtuW5iXQfCNbs9gjEsFecqPv4yffwsgS"
  }
}
EOF
```

**Example response**

```json
{
  "status": "success",
  "data": {
    "custom_referral_code": "trader1"
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Set A Username

`POST <write_base_url>/api/v1/usernames`

Sets, renames, or clears the authenticated owner's Username. This request is signed by an active
trading key and requires a deposited account.

Usernames contain 3 to 20 ASCII letters, digits, underscores, or hyphens. Submitted casing is
preserved, but uniqueness is case-insensitive. Send an empty string to clear the current Username.
An unavailable Username returns `CONFLICT` with the message `That name is taken.`

**Request Body**

| Field | Type | Description |
|---|---|---|
| `username` | string | Owner-chosen Username, or an empty string to clear the current Username. |
| `auth` | [RequestAuth](#requestauth) | Trading-key-signed request authentication metadata. |


**JSON Response Payload**

| Field | Type | Description |
|---|---|---|
| `username` | `Username` | (Optional) The now-active Username, or `null` after a clear. |


**Example request**

```bash
curl -X POST https://trade.pascal.trade/api/v1/usernames \
  -H 'Content-Type: application/json' \
  --data @- <<'EOF'
{
  "username": "Trader",
  "auth": {
    "client_ts_ms": "1731536000000",
    "recv_window_ms": "5000",
    "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "signer": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
    "signature": "2aEt4QQeG3iFTD6tAZvDnfKzna7cnVh18eq6cveGho9mdwfDGLoFjs1fsyYieXuZKKGdpFFCH8VgvVQJ2K1BBmjV"
  }
}
EOF
```

**Example response**

```json
{
  "status": "success",
  "data": {
    "username": "Trader"
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

## Order Entry WebSocket

`GET wss://trade.pascal.trade/ws` upgrades to a WebSocket connection for placing and
cancelling orders.

Submission via WebSocket may be useful to users who want many concurrent orders in
flight and also want guaranteed submission ordering.

Note:
- WebSocket messages sent on one connection enter matching in the order you sent them, so an order can replace or cancel an order whose acknowledgement has not arrived yet (see [Matching Rounds And Priority](general.txt#matching-rounds-and-priority))
- Send up to 128 concurrent messages
  per connection. At the cap the server stops reading the socket until responses are delivered.
- Rate limit of 1,000 requests per second (counting batch items and pings).
- Batch and message size limits are the same as for REST: 50
  requests per frame, 64 KiB per frame.
- Send `{"type":"ping"}` messages to keep the connection open. Connections idle for
  60 seconds are closed.
- Responses do **not** necessarily arrive in the order requests were sent. Use the `id` field on the request envelope to identify responses.

### Client Requests

Send JSON place and cancel messages shaped like

```json
{
  "id": "42",
  "type": "place|cancel|ping",
  "payload": "/* same place or cancel payload as REST */"
}
```

The payload matches the [Place And Replace Orders](#place-and-replace-orders) array for
`place`, or the [Cancel Orders](#cancel-orders) array for `cancel` exactly.

`id` is an optional field echoed back on the message's response, to help the client match responses to requests.

```json
{
  "id": "1",
  "type": "place",
  "payload": [
    {
      "client_order_id": "42",
      "symbol": "SIM_EVENT_1.MARKET_1",
      "side": "BID",
      "price": "0.550000",
      "size": "10",
      "auth": {
        "client_ts_ms": "1731536000000",
        "recv_window_ms": "5000",
        "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
        "signer": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
        "signature": "2rUctQ9bFbuQaUxbXDGRtGm4LMj3GdbYWAW6pjrznAsLvpdH8Eqyx3LgsFx3YzV9cvMfw1ND5T5nChUQZZJ7jEad"
      }
    }
  ]
}
```

```json
{
  "id": "2",
  "type": "cancel",
  "payload": [
    {
      "client_order_id": "42",
      "auth": {
        "client_ts_ms": "1731536000000",
        "recv_window_ms": "5000",
        "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
        "signer": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
        "signature": "591YziUjZzro24mamxgRrSDdYD71NpsDBmU4UGSyrBYbFiWzYaLjR9he1P5DP8djMKMJzHTsZzwRAagvLqgtiXnc"
      }
    }
  ]
}
```

**Ping** keeps the connection alive and verifies the server end-to-end. The server
responds with `{"type":"pong"}`.

### Server Responses

The server sends one response message per request message, but **not necessarily
in request order**. Match request/response messages by the echoed `id`, or match
individual payload entries by `client_order_id`.

```json
{
  "id": "1",
  "type": "place",
  "payload": [
    {
      "status": "success",
      "data": {
        "order": {
          "id": "987654321",
          "client_order_id": "42",
          "symbol": "SIM_EVENT_1.MARKET_1",
          "side": "BID",
          "price": "0.550000",
          "size_original": "10",
          "size_remaining": "7",
          "size_filled": "3",
          "notional_filled": "1.650000",
          "tif": "GTC",
          "type": "LIMIT",
          "post_only": false,
          "reduce_only": false,
          "seq": "67880",
          "update_seq": "67891",
          "place_ts_ms": "1731536000050",
          "update_ts_ms": "1731536000050"
        },
        "fills": [
          {
            "trade_id": "555001",
            "symbol": "SIM_EVENT_1.MARKET_1",
            "side": "BID",
            "fill_price": "0.550000",
            "fill_size": "3",
            "liquidity": "TAKER",
            "order_id": "987654321",
            "client_order_id": "42",
            "fee_usd": "0.000742",
            "collateral_change_usd": "-1.650742",
            "position_size_prev": "0",
            "realized_pnl_usd": "0.000000",
            "seq": "67891",
            "trade_ts_ms": "1731536000050"
          }
        ]
      },
      "seq": "67891",
      "state_time_ms": "1731536000050",
      "server_time_ms": "1731536000123"
    }
  ]
}
```

```json
{
  "id": "2",
  "type": "cancel",
  "payload": [
    {
      "status": "success",
      "data": {
        "id": "987654321",
        "client_order_id": "42",
        "symbol": "SIM_EVENT_1.MARKET_1",
        "side": "BID",
        "price": "0.550000",
        "size_original": "10",
        "size_remaining": "0",
        "size_filled": "3",
        "notional_filled": "1.650000",
        "tif": "GTC",
        "type": "LIMIT",
        "post_only": false,
        "reduce_only": false,
        "seq": "67880",
        "update_seq": "67891",
        "place_ts_ms": "1731536000050",
        "update_ts_ms": "1731536000050"
      },
      "seq": "67891",
      "state_time_ms": "1731536000050",
      "server_time_ms": "1731536000123"
    }
  ]
}
```

Requests rejected before entering the write pipeline (over the rate limit, under
backpressure, unparseable, or over the batch size limit) get an `error` frame
instead, echoing the frame's `id` and the rejected `client_order_ids` (both absent
when they could not be parsed). Unparseable frames carry the parse error in the
`error` frame's message; repeated ones close the connection (see Close Codes).

```json
{
  "id": "3",
  "type": "error",
  "payload": {
    "data": {
      "code": "RATE_LIMITED",
      "message": "rate limited; slow down before retrying"
    },
    "client_order_ids": [
      "42"
    ]
  }
}
```

### Close Codes

| Code | Reason | Meaning |
|---|---|---|
| 1000 | `idle` | No inbound frames and no pending responses for the idle timeout. |
| 1001 | `going_away` | Server restarting; reconnect. |
| 1009 | — | Frame exceeded the 64 KiB message size limit. |
| 4001 | `slow_consumer` | Client stopped reading responses. |
| 4002 | `rate_limited` | Client kept sending after repeated rate-limit errors. |
| 4003 | `malformed_frame` | Client kept sending invalid messages after repeated errors. |

Clients closed with `malformed_frame` or `rate_limited` are rejected on subsequent upgrades with HTTP 429 for several minutes.

## Market Data Endpoints

### Server Time

`GET <read_base_url>/api/v1/time`

Returns the read API server's current wall-clock time in milliseconds.

**JSON Response Payload**

| Field | Type | Description |
|---|---|---|
| `server_time_ms` | u64 string | API server wall-clock time in milliseconds since the Unix epoch. |


```bash
curl 'https://data.pascal.trade/api/v1/time'
```

```json
{
  "status": "success",
  "data": {
    "server_time_ms": "1731536000123"
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Usernames

`GET <read_base_url>/api/v1/usernames?owners={owner_1},{owner_2}`

Returns active Usernames for up to 100 account owners. Owners without a Username are omitted.
The request rejects an empty owner list, duplicate owners, and lists over the limit.

**Query Parameters**

| Field | Type | Description |
|---|---|---|
| `owners` | array of base58 string | Comma-delimited list of account owners whose Usernames should be returned. |


**JSON Response Payload**

| Field | Type | Description |
|---|---|---|
| `usernames` | object mapping base58 string to `Username` | Active Usernames keyed by owner. Requested owners without a Username are omitted. |


```bash
curl 'https://data.pascal.trade/api/v1/usernames?owners=GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB,J2xccRtuG43drESLYznHhLhQkLTdfepcKYbiQ9BsJVaf'
```

```json
{
  "status": "success",
  "data": {
    "usernames": {
      "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB": "Trader"
    }
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Referral Code

`GET <read_base_url>/api/v1/referral-codes/{referral_code}`

Returns whether `referral_code` currently resolves to a Reward Owner, plus the
taker discount terms a referred user receives at registration. Revoked Custom
Referral Codes return `exists: false`. See the [Referral Program](general.txt#referral-program)
for how both sides of a Referral work.

Codes are 4 to 20 characters of lowercase `a-z0-9`; other values are
rejected with `invalid_request`.

**JSON Response Payload**

| Field | Type | Description |
|---|---|---|
| `exists` | boolean | Whether this Referral Code currently resolves to a Reward Owner. |
| `taker_fee_discount_share` | decimal string, 6 d.p. | Fraction of each taker fee discounted for a user referred by this code. |
| `fee_savings_limit_usd` | decimal string, 6 d.p. | Maximum taker fee savings for a user referred by this code. The discount stops after cumulative savings cross this limit. |


```bash
curl 'https://data.pascal.trade/api/v1/referral-codes/k7wq2m4x'
```

```json
{
  "status": "success",
  "data": {
    "exists": true,
    "taker_fee_discount_share": "0.050000",
    "fee_savings_limit_usd": "250.000000"
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### List Markets

`GET <read_base_url>/api/v1/markets`

Returns unresolved markets and their current state, ordered by symbol.

**JSON Response Payload**

Returns a JSON array of market objects. Every element in the array is a JSON object:

#### MarketStateMsg

Contains the market spec, display attributes, and current state exposed by the Read API.

| Field | Type | Description |
|---|---|---|
| `symbol` | string ([Symbol](#market-symbols)) | Human-readable identifier for a market. Globally Unique. Eg "NYCMAYOR_25NOV04.MAMDANI". |
| `taker_fee_rate` | decimal string, 6 d.p. | Base fee rate paid by takers. Decimal string, e.g. "0.0010" for 10 bps. For a trade of sz at px, the taker fee is `sz * px * (1 - px) * taker_fee_rate`. |
| `maker_rebate_share` | decimal string, 6 d.p. | Share of taker fee rebated to makers. Decimal string, e.g. "0.50" for 50%. For a trade of sz at px, the maker earns `sz * px * (1 - px) * taker_fee_rate * maker_rebate_share`. |
| `tick_size_min` | decimal string, 6 d.p. | Minimum tick size. The tick size for a given price `px` is `max(tick_size_min, 10^(floor(log10(px')) - tick_sig_figs + 1))`, where `px' = min(px, 1 - px)`. The intuition is that we want some amount of decimal precision available, but we don't want to count 0 prefixes. For example, 0.0025, 0.025 and 0.25 all have 2 digits of precision. |
| `tick_sig_figs` | integer | Number of significant figures in the tick size formula. Must be in `[1, 6]`. |
| `display_attributes` | object mapping string to JSON value | Market display metadata for UI rendering. Keys and shape match [MarketDisplayAttributes](#marketdisplayattributes). |
| `listing_ts_ms` | u64 string | (Optional) Timestamp when the market was listed, in milliseconds since the Unix epoch. |
| `rules_url` | string | (Optional) URL to the market's resolution rules document, if available. |
| `stats` | [MarketStatsMsg](#marketstatsmsg) | (Optional) Stats. |
| `mark_price` | decimal string, 6 d.p. | (Optional) Median of whichever of (best bid, best ask, last trade) are available. |
| `open_interest` | u64 string | Current open interest. |
| `resolution` | [MarketResolutionMsg](#marketresolutionmsg) | (Optional) Final market resolution, if this market has resolved. |



`display_attributes` object:

#### MarketDisplayAttributes

Additional market attributes used for display purposes only.

| Field | Type | Description |
|---|---|---|
| `event_description` | string | Human-readable description of the event, has to fit in-line. Unenforced max 50 chars. For example, `2025 NYC Mayoral Election`. |
| `market_description` | string | Short label for this market, displayed in the context of `event_description`. For example, `Mamdani` or `Yes`. |
| `reverse_description` | string | (Optional) Short label for this market to display if the user has reversed the UI. Mirrors `market_description`. For example, if the market is YANKEES_VS_METS.YANKEES the market_description might be "Yankees win". In that case the reverse_description would be something like "Mets win". `None` indicates reversing the UI is not available for this market. This is a UI-only field. |
| `colors` | [MarketDisplayColors](#marketdisplaycolors) | (Optional) Theme colors for this market's outcomes, present on head-to-head sections such as a moneyline. Use the values as supplied. |
| `topic` | [TopicInfo](#topicinfo) | (Optional) Higher-level topic this event belongs to, if any. |
| `game_page` | [GamePageDisplayInfo](#gamepagedisplayinfo) | (Optional) Display metadata for sections (game lines) under the same game. When absent, clients should use regular event-based display. |
| `market_type` | [MarketType](#markettype) | (Optional) Typed market semantics for display and validation. |
| `tags` | array of string | First-letter-capitalized tags for filtering and discovery. |
| `expected_event_start_time_ms` | u64 string | (Optional) Expected start time of the event. Indicative, for display only. |
| `expected_resolution_time_ms` | u64 string | Expected date for market resolution. Indicative, for display only. |
| `sort_order` | [MarketSort](#marketsort) | Default UI sort order |
| `scalar` | [RangeDisplayAttributes](#rangedisplayattributes) | (Optional) Scalar-market display metadata. |
| `reference` | [ReferenceAttributes](#referenceattributes) | (Optional) Reference that informs this market's resolution criteria. |


`display_attributes.scalar` object:

#### RangeDisplayAttributes

| Field | Type | Description |
|---|---|---|
| `upper` | i16 string | Upper bound of the scalar market outcome space, from -999 to 999. |
| `lower` | i16 string | Lower bound of the scalar market outcome space, from -999 to 999. |
| `scale` | u8 string | How many decimal points to move over in the bounds. For example, 15 with a scale of 1 is 1.5. |
| `prefix` | string | String to display before the outcome-space price. EG: "$" |
| `suffix` | string | String to display after the outcome-space price. EG: "K", "B", "T" |


`display_attributes.topic` object:

#### TopicInfo

Higher-level category that links related events for display.

| Field | Type | Description |
|---|---|---|
| `id` | string | Stable identifier for grouping and filtering. For display only. |
| `description` | string | Human-readable label for this topic. For display only. |


`display_attributes.game_page` object:

#### GamePageDisplayInfo

Display metadata for sections (game lines) under the same game.

| Field | Type | Description |
|---|---|---|
| `game_id` | string | Stable identifier for grouping and filtering, e.g. `fifa-world-cup-fra-irq-2026-06-22`. |
| `game_description` | string | Human-readable game title, e.g. `France vs Iraq`. |
| `section_id` | string | Stable section (game line) id, e.g. `moneyline`, `spreads`, or `totals`. |
| `section_description` | string | Human-readable section (game line) label, e.g. `Spreads`, `Totals`. |
| `section_display_order` | integer | Section display order within the game. This orders sections, not rows. |
| `row_display_order` | integer | (Optional) Explicit row display order within the section. |
| `subject_id` | string | (Optional) Stable subject slug for team/player-specific rows, e.g. `lionel-messi`. |
| `subject_description` | string | (Optional) Human-readable subject label, e.g. `Lionel Messi`. |
| `value` | string | (Optional) Normalized numeric value for a game line. Spread values are signed from the subject's perspective, e.g. `-1.5`; total values are unsigned, e.g. `2.5`. |


`display_attributes.colors` object, present on head-to-head sections such as a moneyline. Use the color for the active theme as supplied.

#### MarketDisplayColors

Theme colors for a market's outcomes.

| Field | Type | Description |
|---|---|---|
| `market` | [ThemeDisplayColors](#themedisplaycolors) | Colors for the `market_description` outcome. |
| `reverse` | [ThemeDisplayColors](#themedisplaycolors) | (Optional) Colors for the `reverse_description` outcome, when it names the other side of a head-to-head comparison. |


`display_attributes.colors.market` and `display_attributes.colors.reverse` objects:

#### ThemeDisplayColors

A display color for each theme, as an opaque `#RRGGBB` value. Use the one for the active theme as supplied.

| Field | Type | Description |
|---|---|---|
| `light` | string | Color to use on Pascal's light-theme surfaces. |
| `dark` | string | Color to use on Pascal's dark-theme surfaces. |


`display_attributes.market_type` enum:

#### MarketType

Typed market category and category-specific details for a listed market.

Variant fields are flattened into the same object as `kind`. For example, sports markets use `kind: "sports"` with a `sport` value such as `"soccer"`, and company action markets use `kind: "company_action"` with their company action fields alongside it.

| Value |
|---|
| `"sports"` |
| `"company_action"` |


`display_attributes.market_type.sport` enum for `kind: sports` market types:

#### SportsMarketType

Sport-specific market type details.

| Value |
|---|
| `"soccer"` |
| `"baseball"` |
| `"league_of_legends"` |
| `"counter_strike"` |
| `"tennis"` |
| `"football"` |
| `"basketball"` |

**`"soccer"` fields**

| Field | Type | Description |
|---|---|---|
| `sport` | string literal `"soccer"` | Discriminator. |
| `period` | [SoccerPeriod](#soccerperiod) | Period. |
| `teams` | [HomeAwayTeams](#homeawayteams) | Teams. |
| `market` | [SoccerMarket](#soccermarket) | Market. |

**`"baseball"` fields**

| Field | Type | Description |
|---|---|---|
| `sport` | string literal `"baseball"` | Discriminator. |
| `period` | [BaseballPeriod](#baseballperiod) | Period. |
| `teams` | [HomeAwayTeams](#homeawayteams) | Teams. |
| `market` | [BaseballMarket](#baseballmarket) | Market. |

**`"league_of_legends"` fields**

| Field | Type | Description |
|---|---|---|
| `sport` | string literal `"league_of_legends"` | Discriminator. |
| `series_format` | [BestOfSeriesFormat](#bestofseriesformat) | Series format. |
| `teams` | [HomeAwayTeams](#homeawayteams) | Teams. |
| `market` | [LeagueOfLegendsMarket](#leagueoflegendsmarket) | Market. |

**`"counter_strike"` fields**

| Field | Type | Description |
|---|---|---|
| `sport` | string literal `"counter_strike"` | Discriminator. |
| `series_format` | [BestOfSeriesFormat](#bestofseriesformat) | Series format. |
| `teams` | [HomeAwayTeams](#homeawayteams) | Teams. |
| `market` | [CounterStrikeMarket](#counterstrikemarket) | Market. |

**`"tennis"` fields**

| Field | Type | Description |
|---|---|---|
| `sport` | string literal `"tennis"` | Discriminator. |
| `period` | [TennisPeriod](#tennisperiod) | Period. |
| `match_format` | [TennisMatchFormat](#tennismatchformat) | Match format. |
| `teams` | [HomeAwayTeams](#homeawayteams) | Teams. |
| `market` | [TennisMarket](#tennismarket) | Market. |

**`"football"` fields**

| Field | Type | Description |
|---|---|---|
| `sport` | string literal `"football"` | Discriminator. |
| `period` | [FootballPeriod](#footballperiod) | Period. |
| `teams` | [HomeAwayTeams](#homeawayteams) | Teams. |
| `market` | [FootballMarket](#footballmarket) | Market. |

**`"basketball"` fields**

| Field | Type | Description |
|---|---|---|
| `sport` | string literal `"basketball"` | Discriminator. |
| `period` | [BasketballPeriod](#basketballperiod) | Period. |
| `teams` | [HomeAwayTeams](#homeawayteams) | Teams. |
| `market` | [BasketballMarket](#basketballmarket) | Market. |


`display_attributes.market_type.period` enum for soccer markets:

#### SoccerPeriod

Portion of a soccer match that a market settles on.

| Value | Description |
|---|---|
| `"reg_time"` | Regular time plus stoppage time, excluding extra time and penalties. |
| `"first_half"` | First half plus stoppage time, excluding second half, extra time, and penalties. |
| `"second_half"` | Second half plus stoppage time, excluding first half, extra time, and penalties. |


`display_attributes.market_type.period` enum for baseball markets:

#### BaseballPeriod

Portion of a baseball game that a market settles on.

| Value | Description |
|---|---|
| `"full_game"` | Official full-game result, including extra innings. |


`display_attributes.market_type.period` enum for football markets:

#### FootballPeriod

Portion of a football game that a market settles on.

| Value | Description |
|---|---|
| `"full_game"` | Official full-game result, including any overtime. |


`display_attributes.market_type.period` enum for basketball markets:

#### BasketballPeriod

Portion of a basketball game that a market settles on.

| Value | Description |
|---|---|
| `"full_game"` | Official full-game result, including any overtime. |


`display_attributes.market_type.period` enum for tennis markets:

#### TennisPeriod

Portion of a tennis match that a market settles on.

| Value | Description |
|---|---|
| `"full_match"` | Official full-match result, including tiebreaks. |


`display_attributes.market_type.match_format` enum for tennis markets:

#### TennisMatchFormat

Number of sets in a completed tennis match.

| Value |
|---|
| `"best_of_three"` |
| `"best_of_five"` |


`display_attributes.market_type.series_format` enum for best-of esports markets:

#### BestOfSeriesFormat

Format of a best-of series.

| Value |
|---|
| `"best_of_one"` |
| `"best_of_three"` |
| `"best_of_five"` |


`display_attributes.market_type.teams` object for fixture-scoped team sports:

#### HomeAwayTeams

Provider-designated home and away competitors for match-scoped market types.

For neutral-site, esports, and individual-sport matches, home and away provide canonical fixture ordering and do not imply that either competitor is playing at a home venue.

| Field | Type | Description |
|---|---|---|
| `home_name` | string | Full human-readable home team name used in market labels and rules. |
| `home_short_name` | string | (Optional) Concise home team name used in generated fixture and event display labels. When provided, `away_short_name` must also be provided. |
| `home_subject_id` | string | Stable subject slug for the home team. |
| `away_name` | string | Full human-readable away team name used in market labels and rules. |
| `away_short_name` | string | (Optional) Concise away team name used in generated fixture and event display labels. When provided, `home_short_name` must also be provided. |
| `away_subject_id` | string | Stable subject slug for the away team. |


`display_attributes.market_type.market` enum for soccer markets:

#### SoccerMarket

Soccer market types.

| Value |
|---|
| `"moneyline"` |
| `"spread"` |
| `"total_goals"` |
| `"both_teams_to_score"` |

**`"moneyline"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"moneyline"` | Request discriminator. |
| `outcome` | [ThreeWayOutcome](#threewayoutcome) | Outcome. |

**`"spread"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"spread"` | Request discriminator. |
| `team` | [TeamSide](#teamside) | Team. |
| `line` | string | Line. |

**`"total_goals"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"total_goals"` | Request discriminator. |
| `line` | string | Line. |


`display_attributes.market_type.market` enum for baseball markets:

#### BaseballMarket

Market types for a baseball game.

| Value |
|---|
| `"moneyline"` |
| `"spread"` |
| `"total"` |

**`"moneyline"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"moneyline"` | Request discriminator. |
| `outcome` | [TeamSide](#teamside) | Outcome. |

**`"spread"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"spread"` | Request discriminator. |
| `team` | [TeamSide](#teamside) | Team. |
| `line` | string | Line. |

**`"total"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"total"` | Request discriminator. |
| `line` | string | Line. |


`display_attributes.market_type.market` enum for football markets:

#### FootballMarket

Football market types.

| Value |
|---|
| `"moneyline"` |
| `"spread"` |
| `"total_points"` |

**`"moneyline"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"moneyline"` | Request discriminator. |
| `outcome` | [TeamSide](#teamside) | Outcome. |

**`"spread"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"spread"` | Request discriminator. |
| `team` | [TeamSide](#teamside) | Team. |
| `line` | string | Line. |

**`"total_points"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"total_points"` | Request discriminator. |
| `line` | string | Line. |


`display_attributes.market_type.market` enum for basketball markets:

#### BasketballMarket

Basketball market types.

| Value |
|---|
| `"moneyline"` |
| `"spread"` |
| `"total_points"` |

**`"moneyline"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"moneyline"` | Request discriminator. |
| `outcome` | [TeamSide](#teamside) | Outcome. |

**`"spread"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"spread"` | Request discriminator. |
| `team` | [TeamSide](#teamside) | Team. |
| `line` | string | Line. |

**`"total_points"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"total_points"` | Request discriminator. |
| `line` | string | Line. |


`display_attributes.market_type.market` enum for League of Legends markets:

#### LeagueOfLegendsMarket

League of Legends market types.

| Value |
|---|
| `"moneyline"` |
| `"map_winner"` |
| `"map_handicap"` |
| `"total_maps"` |

**`"moneyline"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"moneyline"` | Request discriminator. |
| `outcome` | [TeamSide](#teamside) | Outcome. |

**`"map_winner"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"map_winner"` | Request discriminator. |
| `map_number` | integer | Map number. |
| `outcome` | [TeamSide](#teamside) | Outcome. |

**`"map_handicap"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"map_handicap"` | Request discriminator. |
| `team` | [TeamSide](#teamside) | Team. |
| `line` | string | Line. |

**`"total_maps"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"total_maps"` | Request discriminator. |
| `line` | string | Line. |


`display_attributes.market_type.market` enum for Counter-Strike markets:

#### CounterStrikeMarket

Counter-Strike market types.

| Value |
|---|
| `"moneyline"` |
| `"map_winner"` |
| `"map_handicap"` |
| `"total_maps"` |

**`"moneyline"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"moneyline"` | Request discriminator. |
| `outcome` | [TeamSide](#teamside) | Outcome. |

**`"map_winner"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"map_winner"` | Request discriminator. |
| `map_number` | integer | Map number. |
| `outcome` | [TeamSide](#teamside) | Outcome. |

**`"map_handicap"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"map_handicap"` | Request discriminator. |
| `team` | [TeamSide](#teamside) | Team. |
| `line` | string | Line. |

**`"total_maps"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"total_maps"` | Request discriminator. |
| `line` | string | Line. |


`display_attributes.market_type.market` enum for tennis markets:

#### TennisMarket

Tennis market types.

| Value |
|---|
| `"moneyline"` |
| `"set_handicap"` |
| `"total_sets"` |
| `"total_games"` |

**`"moneyline"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"moneyline"` | Request discriminator. |
| `outcome` | [TeamSide](#teamside) | Outcome. |

**`"set_handicap"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"set_handicap"` | Request discriminator. |
| `team` | [TeamSide](#teamside) | Team. |
| `line` | string | Line. |

**`"total_sets"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"total_sets"` | Request discriminator. |
| `line` | string | Line. |

**`"total_games"` fields**

| Field | Type | Description |
|---|---|---|
| `type` | string literal `"total_games"` | Request discriminator. |
| `line` | string | Line. |


`display_attributes.market_type.market.outcome` enum for moneyline market types that can draw:

#### ThreeWayOutcome

Home, away, or draw outcome for three-way markets.

| Value |
|---|
| `"home"` |
| `"away"` |
| `"draw"` |


`display_attributes.market_type.market.team` enum for team-scoped market types:

#### TeamSide

| Value |
|---|
| `"home"` |
| `"away"` |


`display_attributes.market_type` object for `kind: company_action` market types. The announcement deadline must be 11:59:59 PM ET on its calendar day, and `sort_order` must be `EXPECTED_RESOLUTION_TIME`:

#### CompanyActionMarketType

A company officially announcing an action before a deadline.

| Field | Type | Description |
|---|---|---|
| `company_name` | string | Display name of the company used in market labels and rules, e.g. `Meta`. |
| `action` | string | The action as a noun phrase completing "officially announces ...", e.g. `a partnership with OpenAI`. |
| `announcement_deadline_time_ms` | u64 string | Cutoff for a qualifying announcement. |


`display_attributes.sort_order` enum:

#### MarketSort

An enum encoding the default sort order for markets on the UI

| Value |
|---|
| `"PRICE"` |
| `"SYMBOL_ASC"` |
| `"SYMBOL_DESC"` |
| `"MARKET_DESCRIPTION_ASC"` |
| `"MARKET_DESCRIPTION_DESC"` |
| `"VOLUME"` |
| `"EXPECTED_RESOLUTION_TIME"` |


`display_attributes.reference` enum:

#### ReferenceAttributes

| Value |
|---|
| `"polymarket"` |

**`"polymarket"` fields**

| Field | Type | Description |
|---|---|---|
| `kind` | string literal `"polymarket"` | Discriminator. |
| `market_slug` | string | Polymarket market slug mirrored by this Pascal market. |
| `condition_id` | string | Polymarket condition id for the mirrored CLOB market. |
| `market_outcome_token_id` | string | (Optional) Polymarket CLOB token id for the Pascal market side. If this token wins, the Pascal market resolves to 1.000000. |
| `reverse_outcome_token_id` | string | (Optional) Polymarket CLOB token id for the other binary outcome. If this token wins, the Pascal market resolves to 0.000000. |


`resolution` object:

#### MarketResolutionMsg

Final resolution metadata for a market.

| Field | Type | Description |
|---|---|---|
| `price` | decimal string, 6 d.p. | Final settlement price in dollars. |
| `seq` | u64 string | Matching engine sequence number when the market resolved. |
| `market_resolution_ts_ms` | u64 string | Timestamp when the market resolved, in milliseconds since the Unix epoch. |


`stats` object:

#### MarketStatsMsg

| Field | Type | Description |
|---|---|---|
| `last_24h` | [MarketStatsSnapshotMsg](#marketstatssnapshotmsg) | Rolling 24-hour market statistics snapshot. |
| `all_time` | [MarketStatsSnapshotMsg](#marketstatssnapshotmsg) | All-time market statistics snapshot. |


`last_24h` and `all_time` use the following shape:

#### MarketStatsSnapshotMsg

| Field | Type | Description |
|---|---|---|
| `mark_price_start` | decimal string, 6 d.p. | (Optional) Mark price at the start of the rolling window. |
| `taker_buy_volume` | u64 string | Total base-asset volume bought by takers in the window. |
| `taker_sell_volume` | u64 string | Total base-asset volume sold by takers in the window. |
| `taker_buy_volume_notional` | decimal string, 6 d.p. | Total quote-notional bought by takers in the window. |
| `taker_sell_volume_notional` | decimal string, 6 d.p. | Total quote-notional sold by takers in the window. |
| `taker_buy_trade_count` | u64 string | Total number of buy-side taker trades included in the snapshot window. |
| `taker_sell_trade_count` | u64 string | Total number of sell-side taker trades included in the snapshot window. |
| `window_end_ts_ms_exclusive` | u64 string | Exclusive upper-bound timestamp for the aggregation window. |


For `last_24h`, `window_end_ts_ms_exclusive` is the latest closed minute. Markets
with no history receive a zero snapshot at that boundary.

Resolution does not freeze the 24-hour window. A resolved market keeps its final
price while volume, trades, and earlier prices age out normally. Once the window
begins after resolution, `mark_price_start` is the final price.

```bash
curl 'https://data.pascal.trade/api/v1/markets'
```

```json
{
  "status": "success",
  "data": [
    {
      "symbol": "SIM_EVENT_1.MARKET_1",
      "taker_fee_rate": "0.001000",
      "maker_rebate_share": "0.500000",
      "tick_size_min": "0.010000",
      "tick_sig_figs": 2,
      "display_attributes": {
        "event_description": "API documentation sample market",
        "expected_resolution_time_ms": "1735000000000",
        "market_description": "Yes",
        "reverse_description": "No",
        "sort_order": "SYMBOL_ASC",
        "tags": [
          "Docs"
        ],
        "topic": {
          "id": "docs",
          "description": "Documentation examples"
        }
      },
      "listing_ts_ms": "1731536000000",
      "rules_url": "https://sample-rules-url.com/events/SIM_EVENT_1/SIM_EVENT_1.MARKET_1.md",
      "stats": {
        "last_24h": {
          "mark_price_start": "0.520000",
          "taker_buy_volume": "120",
          "taker_sell_volume": "90",
          "taker_buy_volume_notional": "64.800000",
          "taker_sell_volume_notional": "48.600000",
          "taker_buy_trade_count": "18",
          "taker_sell_trade_count": "14",
          "window_end_ts_ms_exclusive": "1731535980000"
        },
        "all_time": {
          "taker_buy_volume": "1200",
          "taker_sell_volume": "900",
          "taker_buy_volume_notional": "648.000000",
          "taker_sell_volume_notional": "486.000000",
          "taker_buy_trade_count": "180",
          "taker_sell_trade_count": "140",
          "window_end_ts_ms_exclusive": "1731535980000"
        }
      },
      "mark_price": "0.550000",
      "open_interest": "250"
    }
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Resolved Markets

`GET <read_base_url>/api/v1/markets/resolved`

Returns markets resolved within the requested `lookback`.

**Query Parameters**

| Field | Type | Description |
|---|---|---|
| `lookback` | string | Optional. Accepted values: `4h`, `24h`, `3d`. Defaults to `24h`. |
| `order_by` | string | Optional. Accepted values: `resolution_time`, `volume_24h`, `volume_all_time`. Defaults to `resolution_time`. |
| `limit` | integer | Optional. Maximum number of markets to return. Must be one of `50`, `100`, or `200`. Defaults to 50. |

`order_by` enum:

#### ResolvedMarketOrderBy

Resolved market ordering field.

| Value | Description |
|---|---|
| `"resolution_time"` | Sort by least distance between market resolution time and current exchange time. |
| `"volume_24h"` | Sort by rolling 24-hour contract volume. |
| `"volume_all_time"` | Sort by all-time contract volume. |


`order_by` behavior:

| Value | Description |
|---|---|
| `resolution_time` | Sort by least distance between resolution time and the current exchange time. For this endpoint, that returns the latest resolutions first. |
| `volume_24h` | Sort by rolling 24-hour contract volume. Ties use the `resolution_time` ordering. |
| `volume_all_time` | Sort by all-time contract volume. |

Resolved markets use the rolling-statistics semantics described under
[List Markets](#list-markets).

**JSON Response Payload**

Returns a JSON array of market objects. Same object shape as `GET /api/v1/markets`.

```bash
curl 'https://data.pascal.trade/api/v1/markets/resolved?lookback=24h&order_by=resolution_time&limit=50'
```

```json
{
  "status": "success",
  "data": [
    {
      "symbol": "SIM_EVENT_1.MARKET_1",
      "taker_fee_rate": "0.001000",
      "maker_rebate_share": "0.500000",
      "tick_size_min": "0.010000",
      "tick_sig_figs": 2,
      "display_attributes": {
        "event_description": "API documentation sample market",
        "expected_resolution_time_ms": "1731536000050",
        "market_description": "Yes",
        "reverse_description": "No",
        "sort_order": "SYMBOL_ASC",
        "tags": [
          "Docs"
        ],
        "topic": {
          "id": "docs",
          "description": "Documentation examples"
        }
      },
      "listing_ts_ms": "1731536000000",
      "rules_url": "https://sample-rules-url.com/events/SIM_EVENT_1/SIM_EVENT_1.MARKET_1.md",
      "stats": {
        "last_24h": {
          "mark_price_start": "0.520000",
          "taker_buy_volume": "120",
          "taker_sell_volume": "90",
          "taker_buy_volume_notional": "64.800000",
          "taker_sell_volume_notional": "48.600000",
          "taker_buy_trade_count": "18",
          "taker_sell_trade_count": "14",
          "window_end_ts_ms_exclusive": "1731535980000"
        },
        "all_time": {
          "taker_buy_volume": "1200",
          "taker_sell_volume": "900",
          "taker_buy_volume_notional": "648.000000",
          "taker_sell_volume_notional": "486.000000",
          "taker_buy_trade_count": "180",
          "taker_sell_trade_count": "140",
          "window_end_ts_ms_exclusive": "1731535980000"
        }
      },
      "mark_price": "1.000000",
      "open_interest": "0",
      "resolution": {
        "price": "1.000000",
        "seq": "67891",
        "market_resolution_ts_ms": "1731536000050"
      }
    }
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

#### Market Symbols

Symbols are uppercase ASCII identifiers up to 32 bytes
long, of the form `EVENT.MARKET`. The event prefix groups markets that share a
resolution event; the market suffix identifies the specific outcome.

For example, `NYCMAYOR_25NOV04.MAMDANI` denotes the "Mamdani" outcome of the
2025-11-04 New York City mayoral election event. A second outcome on the same
event might be `NYCMAYOR_25NOV04.ADAMS`.

Symbols are immutable and globally unique.

### Market Search

`POST <read_base_url>/api/v1/markets/search`

Returns markets matching any requested symbol, event, or game. Symbol, event,
and game filters are exact-match filters combined with union semantics. At least
one filter is required. Search results include resolved markets.

Requests may include at most 500 symbols,
at most 50 event codes, and at most
50 games.

Markets are ordered by symbol.

Resolved markets use the rolling-statistics semantics described under
[List Markets](#list-markets).

**JSON Request Body**

| Field | Type | Description |
|---|---|---|
| `symbols` | array of string ([Symbol](#market-symbols)) | (Optional) Exact symbols to match. Maximum 500 symbols. |
| `events` | array of string | (Optional) Exact event codes to match. Maximum 50 event codes. |
| `games` | array of string | (Optional) Exact game ids to match. Maximum 50 games. |


**JSON Response Payload**

Returns a JSON array of market objects. Same object shape as `GET /api/v1/markets`.

```bash
curl -X POST https://data.pascal.trade/api/v1/markets/search \
  -H 'Content-Type: application/json' \
  --data @- <<'EOF'
{
  "symbols": [
    "SIM_EVENT_1.MARKET_1"
  ],
  "events": [
    "SIM_EVENT_1"
  ],
  "games": [
    "fifa-world-cup-fra-irq-2026-06-22"
  ]
}
EOF
```

```json
{
  "status": "success",
  "data": [
    {
      "symbol": "SIM_EVENT_1.MARKET_1",
      "taker_fee_rate": "0.001000",
      "maker_rebate_share": "0.500000",
      "tick_size_min": "0.010000",
      "tick_sig_figs": 2,
      "display_attributes": {
        "event_description": "API documentation sample market",
        "expected_resolution_time_ms": "1735000000000",
        "market_description": "Yes",
        "reverse_description": "No",
        "sort_order": "SYMBOL_ASC",
        "tags": [
          "Docs"
        ],
        "topic": {
          "id": "docs",
          "description": "Documentation examples"
        }
      },
      "listing_ts_ms": "1731536000000",
      "rules_url": "https://sample-rules-url.com/events/SIM_EVENT_1/SIM_EVENT_1.MARKET_1.md",
      "stats": {
        "last_24h": {
          "mark_price_start": "0.520000",
          "taker_buy_volume": "120",
          "taker_sell_volume": "90",
          "taker_buy_volume_notional": "64.800000",
          "taker_sell_volume_notional": "48.600000",
          "taker_buy_trade_count": "18",
          "taker_sell_trade_count": "14",
          "window_end_ts_ms_exclusive": "1731535980000"
        },
        "all_time": {
          "taker_buy_volume": "1200",
          "taker_sell_volume": "900",
          "taker_buy_volume_notional": "648.000000",
          "taker_sell_volume_notional": "486.000000",
          "taker_buy_trade_count": "180",
          "taker_sell_trade_count": "140",
          "window_end_ts_ms_exclusive": "1731535980000"
        }
      },
      "mark_price": "0.550000",
      "open_interest": "250"
    }
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Market Text Search

`POST <read_base_url>/api/v1/markets/text-search`

Returns markets whose symbol, event description, market description, or tag contains
the requested text. Matching is case-insensitive substring matching. If `tags`
is provided, every returned market must contain all requested tags exactly.

Requests must include a query between 3 and 64 characters after trimming.
Missing or type-invalid fields fail JSON request parsing; blank, too-short, or
too-long trimmed queries return `INVALID_REQUEST`.

Results are ordered by `order_by`. `limit` defaults to 50 and may not exceed 100.

Resolved markets use the rolling-statistics semantics described under
[List Markets](#list-markets).

**JSON Request Body**

| Field | Type | Description |
|---|---|---|
| `query` | string | Case-insensitive substring query. Trimmed length must be 3 to 64 Unicode scalar chars. |
| `tags` | array of string | (Optional) Exact display-attribute tags all returned markets must contain. Maximum 5 tags. |
| `status` | [MarketStatusFilter](#marketstatusfilter) | (Optional) Resolution status filter. |
| `order_by` | [MarketSearchOrderBy](#marketsearchorderby) | (Optional) Market field used for result ordering. |
| `limit` | integer | (Optional) Maximum number of markets to return. Defaults to 50. Maximum 100. |


`status` enum:

#### MarketStatusFilter

Market lifecycle status filter.

| Value | Description |
|---|---|
| `"live"` | Include unresolved markets only. |
| `"resolved"` | Include resolved markets only. |
| `"all"` | Include both unresolved and resolved markets. |


`order_by` enum:

#### MarketSearchOrderBy

Market text-search ordering field.

| Value | Description |
|---|---|
| `"volume_24h"` | Sort by rolling 24-hour contract volume. |
| `"volume_all_time"` | Sort by all-time contract volume. |


`order_by` behavior:

| Value | Description |
|---|---|
| `volume_24h` | Sort by rolling 24-hour contract volume descending, then by symbol ascending. |
| `volume_all_time` | Sort by all-time contract volume descending, then by symbol ascending. |

**JSON Response Payload**

Returns a JSON array of market objects. Same object shape as `GET /api/v1/markets`.

```bash
curl -X POST https://data.pascal.trade/api/v1/markets/text-search \
  -H 'Content-Type: application/json' \
  --data @- <<'EOF'
{
  "query": "api",
  "tags": [
    "Finance"
  ],
  "status": "live",
  "order_by": "volume_24h",
  "limit": 25
}
EOF
```

```json
{
  "status": "success",
  "data": [
    {
      "symbol": "SIM_EVENT_1.MARKET_1",
      "taker_fee_rate": "0.001000",
      "maker_rebate_share": "0.500000",
      "tick_size_min": "0.010000",
      "tick_sig_figs": 2,
      "display_attributes": {
        "event_description": "API documentation sample market",
        "expected_resolution_time_ms": "1735000000000",
        "market_description": "Yes",
        "reverse_description": "No",
        "sort_order": "SYMBOL_ASC",
        "tags": [
          "Docs"
        ],
        "topic": {
          "id": "docs",
          "description": "Documentation examples"
        }
      },
      "listing_ts_ms": "1731536000000",
      "rules_url": "https://sample-rules-url.com/events/SIM_EVENT_1/SIM_EVENT_1.MARKET_1.md",
      "stats": {
        "last_24h": {
          "mark_price_start": "0.520000",
          "taker_buy_volume": "120",
          "taker_sell_volume": "90",
          "taker_buy_volume_notional": "64.800000",
          "taker_sell_volume_notional": "48.600000",
          "taker_buy_trade_count": "18",
          "taker_sell_trade_count": "14",
          "window_end_ts_ms_exclusive": "1731535980000"
        },
        "all_time": {
          "taker_buy_volume": "1200",
          "taker_sell_volume": "900",
          "taker_buy_volume_notional": "648.000000",
          "taker_sell_volume_notional": "486.000000",
          "taker_buy_trade_count": "180",
          "taker_sell_trade_count": "140",
          "window_end_ts_ms_exclusive": "1731535980000"
        }
      },
      "mark_price": "0.550000",
      "open_interest": "250"
    }
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Order Books

`GET <read_base_url>/api/v1/books`

Returns order books for up to 50 comma-delimited symbols.

Single-symbol responses may be up to one second old. For live order books, use
the `book` WebSocket channel, which starts with a full snapshot and then streams
updates.

**Query Parameters**

| Field | Type | Description |
|---|---|---|
| `symbols` | comma-separated array of string ([Symbol](#market-symbols)) | Comma-delimited list of market symbols. |


**JSON Response Payload**

| Field | Type | Description |
|---|---|---|
| `books` | object mapping string ([Symbol](#market-symbols)) to [OrderBookMsg](#orderbookmsg) | Order books keyed by market symbol. |


Each value in `books` is an order book object:

#### OrderBookMsg

Order book message for API responses.

Levels are (price, size) tuples serialized as string arrays: `[["0.50", "100"], ...]`

| Field | Type | Description |
|---|---|---|
| `asks` | array of tuple (decimal string, 6 d.p., u64 string) | Ask levels as `(price, size)` tuples, sorted lowest price first. |
| `bids` | array of tuple (decimal string, 6 d.p., u64 string) | Bid levels as `(price, size)` tuples, sorted highest price first. |
| `spec` | [MarketSpec](#marketspec) | (Optional) Market specification for this book, included on first fetch or when the market specification changes. |


`spec` object:

#### MarketSpec

Specification for a tradeable market.

| Field | Type | Description |
|---|---|---|
| `symbol` | string ([Symbol](#market-symbols)) | Human-readable identifier for a market. Globally Unique. Eg "NYCMAYOR_25NOV04.MAMDANI". |
| `taker_fee_rate` | decimal string, 6 d.p. | Base fee rate paid by takers. Decimal string, e.g. "0.0010" for 10 bps. For a trade of sz at px, the taker fee is `sz * px * (1 - px) * taker_fee_rate`. |
| `maker_rebate_share` | decimal string, 6 d.p. | Share of taker fee rebated to makers. Decimal string, e.g. "0.50" for 50%. For a trade of sz at px, the maker earns `sz * px * (1 - px) * taker_fee_rate * maker_rebate_share`. |
| `tick_size_min` | decimal string, 6 d.p. | Minimum tick size. The tick size for a given price `px` is `max(tick_size_min, 10^(floor(log10(px')) - tick_sig_figs + 1))`, where `px' = min(px, 1 - px)`. The intuition is that we want some amount of decimal precision available, but we don't want to count 0 prefixes. For example, 0.0025, 0.025 and 0.25 all have 2 digits of precision. |
| `tick_sig_figs` | integer | Number of significant figures in the tick size formula. Must be in `[1, 6]`. |


```bash
curl 'https://data.pascal.trade/api/v1/books?symbols=SIM_EVENT_1.MARKET_1,SIM_EVENT_1.MARKET_2'
```

```json
{
  "status": "success",
  "data": {
    "books": {
      "SIM_EVENT_1.MARKET_1": {
        "asks": [
          [
            "0.560000",
            "12"
          ],
          [
            "0.570000",
            "20"
          ]
        ],
        "bids": [
          [
            "0.540000",
            "15"
          ],
          [
            "0.530000",
            "7"
          ]
        ],
        "spec": {
          "symbol": "SIM_EVENT_1.MARKET_1",
          "taker_fee_rate": "0.001000",
          "maker_rebate_share": "0.500000",
          "tick_size_min": "0.010000",
          "tick_sig_figs": 2
        }
      },
      "SIM_EVENT_1.MARKET_2": {
        "asks": [
          [
            "0.560000",
            "12"
          ],
          [
            "0.570000",
            "20"
          ]
        ],
        "bids": [
          [
            "0.540000",
            "15"
          ],
          [
            "0.530000",
            "7"
          ]
        ]
      }
    }
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Trade Candles

`GET <read_base_url>/api/v1/trade-candles`

Returns OHLCV trade candles for one market and interval. Ranges are end-exclusive. If
`start_time_ms` is omitted, `count_back` controls how many candles are returned before
`end_time_ms`. `interval` must be one of `1m`, `5m`, `15m`, `1h`, `4h`, `12h`, and `1d`. `count_back`
defaults to 100 and must be between
1 and 500.

**Query Parameters**

| Field | Type | Description |
|---|---|---|
| `symbol` | string ([Symbol](#market-symbols)) | Symbol of the market to fetch candles for. |
| `interval` | string enum: `"1m"`, `"5m"`, `"15m"`, `"1h"`, `"4h"`, `"12h"`, `"1d"` | Candle aggregation interval. |
| `end_time_ms` | integer | Exclusive end timestamp for the query range, in milliseconds since the Unix epoch. |
| `start_time_ms` | integer | (Optional) Inclusive start timestamp for the query range. If omitted, use `count_back`. |
| `count_back` | integer | (Optional) Number of candles to return ending at `end_time_ms` when `start_time_ms` is omitted. |


**JSON Response Payload**

Returns a JSON array of candle objects. Every element in the array is a JSON object:

#### CandleMsg

OHLCV candle in TradingView-compatible format.

| Field | Type | Description |
|---|---|---|
| `time` | u64 string | Candle open time in milliseconds since the Unix epoch. |
| `open` | decimal string, 6 d.p. | Opening price in dollars. |
| `high` | decimal string, 6 d.p. | Highest price in the interval, in dollars. |
| `low` | decimal string, 6 d.p. | Lowest price in the interval, in dollars. |
| `close` | decimal string, 6 d.p. | Closing price in dollars. |
| `volume` | u64 string | Total contracts traded in the interval. |
| `taker_buy_volume` | u64 string | Contracts bought by takers in the interval. |
| `taker_sell_volume` | u64 string | Contracts sold by takers in the interval. |
| `volume_notional` | decimal string, 6 d.p. | Total price * size traded in the interval. |
| `taker_buy_volume_notional` | decimal string, 6 d.p. | Price * size bought by takers in the interval. |
| `taker_sell_volume_notional` | decimal string, 6 d.p. | Price * size sold by takers in the interval. |
| `trade_count` | u64 string | Total number of trades in the interval. |
| `taker_buy_count` | u64 string | Number of taker buy trades in the interval. |
| `taker_sell_count` | u64 string | Number of taker sell trades in the interval. |


```bash
curl 'https://data.pascal.trade/api/v1/trade-candles?symbol=SIM_EVENT_1.MARKET_1&interval=1m&end_time_ms=1731536000000&count_back=2'
```

```json
{
  "status": "success",
  "data": [
    {
      "time": "1731535960000",
      "open": "0.520000",
      "high": "0.570000",
      "low": "0.510000",
      "close": "0.550000",
      "volume": "120",
      "taker_buy_volume": "70",
      "taker_sell_volume": "50",
      "volume_notional": "66.000000",
      "taker_buy_volume_notional": "38.500000",
      "taker_sell_volume_notional": "27.500000",
      "trade_count": "8",
      "taker_buy_count": "5",
      "taker_sell_count": "3"
    }
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Mark Price Candles

`GET <read_base_url>/api/v1/mark-price-candles`

Returns sparse mark price OHLC candles for one market and interval. Ranges are end-exclusive. If
`start_time_ms` is omitted, `count_back` controls how many candles are returned before
`end_time_ms`. `interval` must be one of `1m`, `5m`, `15m`, `1h`, `4h`, `12h`, and `1d`. `count_back`
defaults to 100 and must be between
1 and 500.

**Query Parameters**

| Field | Type | Description |
|---|---|---|
| `symbol` | string ([Symbol](#market-symbols)) | Symbol of the market to fetch mark price candles for. |
| `interval` | string enum: `"1m"`, `"5m"`, `"15m"`, `"1h"`, `"4h"`, `"12h"`, `"1d"` | Candle aggregation interval. |
| `end_time_ms` | integer | Exclusive end timestamp for the query range, in milliseconds since the Unix epoch. |
| `start_time_ms` | integer | (Optional) Inclusive start timestamp for the query range. If omitted, use `count_back`. |
| `count_back` | integer | (Optional) Number of candles to return ending at `end_time_ms` when `start_time_ms` is omitted. |


**JSON Response Payload**

Returns a JSON array of mark price candle objects. Every element in the array is a JSON object:

#### MarkPriceCandleMsg

Mark price OHLC candle.

| Field | Type | Description |
|---|---|---|
| `time` | u64 string | Candle open time in milliseconds since the Unix epoch. |
| `open` | decimal string, 6 d.p. | Opening mark price in dollars. |
| `high` | decimal string, 6 d.p. | Highest mark price in the interval, in dollars. |
| `low` | decimal string, 6 d.p. | Lowest mark price in the interval, in dollars. |
| `close` | decimal string, 6 d.p. | Closing mark price in dollars. |


```bash
curl 'https://data.pascal.trade/api/v1/mark-price-candles?symbol=SIM_EVENT_1.MARKET_1&interval=1m&end_time_ms=1731536000000&count_back=2'
```

```json
{
  "status": "success",
  "data": [
    {
      "time": "1731535960000",
      "open": "0.540000",
      "high": "0.580000",
      "low": "0.530000",
      "close": "0.560000"
    }
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Batch Mark Price Candles

`GET <read_base_url>/api/v1/mark-price-candles/batch`

Returns sparse mark price OHLC candles for up to 20
symbols sharing one interval and time range.

Uses the same range semantics as `GET /api/v1/mark-price-candles`, except
`count_back` and explicit range queries are capped at
200 candles per symbol.

Unknown symbols are omitted from `items`; returned items preserve request order.

**Query Parameters**

| Field | Type | Description |
|---|---|---|
| `symbols` | comma-separated array of string ([Symbol](#market-symbols)) | Comma-delimited list of market symbols to fetch mark price candles for. |
| `interval` | string enum: `"1m"`, `"5m"`, `"15m"`, `"1h"`, `"4h"`, `"12h"`, `"1d"` | Candle aggregation interval. |
| `end_time_ms` | integer | Exclusive end timestamp for the query range, in milliseconds since the Unix epoch. |
| `start_time_ms` | integer | (Optional) Inclusive start timestamp for the query range. If omitted, use `count_back`. |
| `count_back` | integer | (Optional) Number of candles to return ending at `end_time_ms` when `start_time_ms` is omitted. |


**JSON Response Payload**

| Field | Type | Description |
|---|---|---|
| `items` | array of [MarkPriceCandlesBatchItem](#markpricecandlesbatchitem) | Per-symbol candle results. Unknown requested symbols are omitted. |


Each value in `items` is a JSON object:

#### MarkPriceCandlesBatchItem

Mark price candle data for one requested symbol.

| Field | Type | Description |
|---|---|---|
| `symbol` | string ([Symbol](#market-symbols)) | Market symbol for this result. |
| `candles` | array of [MarkPriceCandleMsg](#markpricecandlemsg) | Mark price candles for this symbol, sorted newest-first. |


Each value in `candles` is a mark price candle object using
[MarkPriceCandleMsg](#markpricecandlemsg).

```bash
curl 'https://data.pascal.trade/api/v1/mark-price-candles/batch?symbols=SIM_EVENT_1.MARKET_1,SIM_EVENT_1.MARKET_2&interval=1m&end_time_ms=1731536000000&count_back=2'
```

```json
{
  "status": "success",
  "data": {
    "items": [
      {
        "symbol": "SIM_EVENT_1.MARKET_1",
        "candles": [
          {
            "time": "1731535960000",
            "open": "0.540000",
            "high": "0.580000",
            "low": "0.530000",
            "close": "0.560000"
          }
        ]
      },
      {
        "symbol": "SIM_EVENT_1.MARKET_2",
        "candles": []
      }
    ]
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Trades

`GET <read_base_url>/api/v1/trades`

Returns trade history for up to 120 markets.

**Query Parameters**

| Field | Type | Description |
|---|---|---|
| `symbols` | comma-separated array of string ([Symbol](#market-symbols)) | Comma-delimited list of market symbols. |
| `before_cursor` | string | (Optional) Opaque cursor returned as `next_cursor` from a prior page. Results are strictly older than this cursor. |
| `at_or_before_seq` | u64 string | (Optional) Inclusive sequence number to start pagination from. Use this when you have an event (eg a fill or order) and want to start pagination from that event. After you get the first page, use the `next_cursor` to continue. |
| `limit` | integer | (Optional) Maximum number of items to return. |


**JSON Response Payload**

Returns a paginated JSON object:

| Field | Type | Description |
|---|---|---|
| `items` | array of [PublicTradeMsg](#publictrademsg) | Result page items. |
| `next_cursor` | string | (Optional) Cursor for the next page of results. Omitted on the last page. |


Every element in `items` is a JSON object:

#### PublicTradeMsg

Public trade message.

This is not the same as the account-specific [FillMsg](#fillmsg), which is a view of *one side* of a trade, from one account's perspective.

| Field | Type | Description |
|---|---|---|
| `trade_id` | u64 string | Unique ID for this trade. |
| `symbol` | string ([Symbol](#market-symbols)) | Market symbol this trade belongs to. |
| `taker_side` | string enum: `"BID"`, `"ASK"` | Side of the aggressive order that took liquidity. |
| `price` | decimal string, 6 d.p. | Trade price in dollars. |
| `size` | u64 string | Trade size in contracts. |
| `maker` | base58 string | Account owner public key of the resting (maker) order. |
| `taker` | base58 string | Account owner public key of the aggressive (taker) order. |
| `seq` | u64 string | Matching engine sequence number when this trade occurred. |
| `trade_ts_ms` | u64 string | Timestamp when this trade occurred, in milliseconds since the Unix epoch. |


```bash
curl 'https://data.pascal.trade/api/v1/trades?symbols=SIM_EVENT_1.MARKET_1&limit=50'
```

```json
{
  "status": "success",
  "data": {
    "items": [
      {
        "trade_id": "555001",
        "symbol": "SIM_EVENT_1.MARKET_1",
        "taker_side": "BID",
        "price": "0.550000",
        "size": "3",
        "maker": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
        "taker": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
        "seq": "67891",
        "trade_ts_ms": "1731536000050"
      }
    ],
    "next_cursor": "00000000000000067890:0000000000"
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

Next-page request using the `data.next_cursor` value above as `before_cursor`:

```bash
curl 'https://data.pascal.trade/api/v1/trades?symbols=SIM_EVENT_1.MARKET_1&before_cursor=00000000000000067890%3A0000000000&limit=50'
```

### Batch Trades

`GET <read_base_url>/api/v1/trades/batch`

Returns the most recent trades for up to 20
markets, newest-first per market. This is the batch equivalent of the first page
of `GET /api/v1/trades`.

Unknown symbols are omitted from `items`; returned items preserve request order.
`limit` defaults to 10 and must be between
1 and 50.

**Query Parameters**

| Field | Type | Description |
|---|---|---|
| `symbols` | comma-separated array of string ([Symbol](#market-symbols)) | Comma-delimited list of market symbols to fetch recent trades for. |
| `limit` | integer | (Optional) Maximum number of recent trades to return per symbol. Defaults to 10. Maximum 50. |


**JSON Response Payload**

| Field | Type | Description |
|---|---|---|
| `items` | array of [TradesBatchItem](#tradesbatchitem) | Per-symbol recent trade results. Unknown requested symbols are omitted. |


Each value in `items` is a JSON object:

#### TradesBatchItem

Recent trades for one requested symbol.

| Field | Type | Description |
|---|---|---|
| `symbol` | string ([Symbol](#market-symbols)) | Market symbol for this result. |
| `trades` | array of [PublicTradeMsg](#publictrademsg) | Recent trades for this symbol, sorted newest-first. |


Each value in `trades` is a public trade object using [PublicTradeMsg](#publictrademsg).

```bash
curl 'https://data.pascal.trade/api/v1/trades/batch?symbols=SIM_EVENT_1.MARKET_1,SIM_EVENT_1.MARKET_2&limit=10'
```

```json
{
  "status": "success",
  "data": {
    "items": [
      {
        "symbol": "SIM_EVENT_1.MARKET_1",
        "trades": [
          {
            "trade_id": "555001",
            "symbol": "SIM_EVENT_1.MARKET_1",
            "taker_side": "BID",
            "price": "0.550000",
            "size": "3",
            "maker": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
            "taker": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
            "seq": "67891",
            "trade_ts_ms": "1731536000050"
          }
        ]
      },
      {
        "symbol": "SIM_EVENT_1.MARKET_2",
        "trades": [
          {
            "trade_id": "555001",
            "symbol": "SIM_EVENT_1.MARKET_2",
            "taker_side": "BID",
            "price": "0.550000",
            "size": "3",
            "maker": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
            "taker": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
            "seq": "67891",
            "trade_ts_ms": "1731536000050"
          }
        ]
      }
    ]
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Top Holders

`GET <read_base_url>/api/v1/top-holders`

Returns the largest active position holders across up to
120 comma-delimited symbols, split into
`longs` (positive position size) and `shorts` (negative position size) per
market. `limit` applies to each side independently. Each side is ordered by
absolute contract size descending, then owner public-key byte order ascending.
Requested symbols for resolved markets are returned with empty `longs` and
`shorts` arrays because they no longer have active positions.

**Query Parameters**

| Field | Type | Description |
|---|---|---|
| `symbols` | comma-separated array of string ([Symbol](#market-symbols)) | Comma-delimited list of market symbols. |
| `limit` | integer | (Optional) Maximum number of holders to return per side per market. Defaults to 10. Maximum 50. |


**JSON Response Payload**

| Field | Type | Description |
|---|---|---|
| `holders` | object mapping string ([Symbol](#market-symbols)) to [MarketTopHoldersMsg](#markettopholdersmsg) | Largest active holders per side, keyed by market symbol. |


Each value in `holders` is a JSON object:

#### MarketTopHoldersMsg

Largest active holders for one market, split by position side.

| Field | Type | Description |
|---|---|---|
| `longs` | array of [TopHolderMsg](#topholdermsg) | Largest long positions, ordered by contracts descending. |
| `shorts` | array of [TopHolderMsg](#topholdermsg) | Largest short positions, ordered by absolute contracts descending. |


Every holder row in `longs` and `shorts` is a JSON object. See
[Realized and Unrealized PnL](general.txt#realized-and-unrealized-pnl) for the `position`
lifecycle, average entry price, and PnL semantics:

#### TopHolderMsg

Holder row for a market.

| Field | Type | Description |
|---|---|---|
| `owner` | base58 string | Account owner public key. |
| `position` | [PositionMsg](#positionmsg) | The holder's current position in this market. |


```bash
curl 'https://data.pascal.trade/api/v1/top-holders?symbols=SIM_EVENT_1.MARKET_1,SIM_EVENT_1.MARKET_2&limit=20'
```

```json
{
  "status": "success",
  "data": {
    "holders": {
      "SIM_EVENT_1.MARKET_1": {
        "longs": [
          {
            "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
            "position": {
              "symbol": "SIM_EVENT_1.MARKET_1",
              "size": "3",
              "cumulative_fees_usd": "0.000742",
              "realized_pnl_usd": "0.000000",
              "unrealized_pnl_usd": "0.000000",
              "mark_price": "0.550000",
              "average_entry_price": "0.550000",
              "seq": "67880",
              "update_seq": "67891",
              "open_ts_ms": "1731535900000",
              "update_ts_ms": "1731536000050"
            }
          }
        ],
        "shorts": []
      },
      "SIM_EVENT_1.MARKET_2": {
        "longs": [],
        "shorts": [
          {
            "owner": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
            "position": {
              "symbol": "SIM_EVENT_1.MARKET_2",
              "size": "-80",
              "cumulative_fees_usd": "0.019800",
              "realized_pnl_usd": "0.000000",
              "unrealized_pnl_usd": "1.600000",
              "mark_price": "0.530000",
              "average_entry_price": "0.550000",
              "seq": "67880",
              "update_seq": "67891",
              "open_ts_ms": "1731535900000",
              "update_ts_ms": "1731536000050"
            }
          }
        ]
      }
    }
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

## Account Data Endpoints

All account data endpoints use `{owner}` as a path parameter. `owner` is the
account owner's Solana address, encoded as the base58 wallet public key that
identifies the Pascal account.

### Account State Snapshot

`GET <read_base_url>/api/v1/accounts/{owner}`

Returns open orders, positions, pending deposits/withdrawals, and collateral for one
account, with orders and positions optionally filtered to a single market.
The same shape is sent over the [account WebSocket channel](#account-channel).

Successful responses may be served from cache for up to 1 second, so a snapshot
fetched immediately after submitting an order may not reflect it yet. For
real-time account state, subscribe to the
[account WebSocket channel](#account-channel).

**Query Parameters**

| Field | Type | Description |
|---|---|---|
| `symbol` | string ([Symbol](#market-symbols)) | (Optional) Market symbol to filter by. When set, `orders` and `positions` contain only that market's entries; account-wide fields such as collateral are unaffected. Omit to include all markets. |
| `exclude_orders` | boolean | (Optional) Return account state with an empty `orders` array. Defaults to false. |


**JSON Response Payload**

| Field | Type | Description |
|---|---|---|
| `username` | `Username` | (Optional) Owner-chosen handle. Present in REST responses and WebSocket subscription snapshots when set; always omitted from incremental WebSocket updates. |
| `twitter_account_connection` | [TwitterAccountConnection](#twitteraccountconnection) | (Optional) Twitter account connected to the owner. Present in REST responses and WebSocket subscription snapshots when connected; always omitted from incremental WebSocket updates. |
| `collateral_usd` | decimal string, 6 d.p. | (Optional) Current free collateral in USD. The account WebSocket channel omits this field when there has been no collateral change since the last snapshot. |
| `rewards` | [AccountRewardsMsg](#accountrewardsmsg) | (Optional) Complete cumulative account reward totals. Present in REST and WebSocket snapshots. The account WebSocket channel omits this field when no reward component changed since the last snapshot. |
| `lifetime_stats` | [AccountLifetimeStatsMsg](#accountlifetimestatsmsg) | (Optional) Complete account lifetime trade totals. Omitted if data is not available. The account WebSocket channel also omits this field when no trade has changed the totals since the last snapshot. |
| `orders` | array of [OrderMsg](#ordermsg) | Open orders for this account, or all changed orders when used on the account WebSocket channel. |
| `positions` | array of [PositionMsg](#positionmsg) | Current open positions for this account, or all changed positions when used on the account WebSocket channel. |
| `pending_deposits` | array of [DepositMsg](#depositmsg) | Deposits being processed onchain but not yet credited. |
| `pending_withdrawals` | array of [PendingWithdrawalMsg](#pendingwithdrawalmsg) | Active pending withdrawals. |


When present, `twitter_account_connection` is a Twitter account connection object:

#### TwitterAccountConnection

Twitter account connected to one Pascal owner.

| Field | Type | Description |
|---|---|---|
| `twitter_user_id` | u64 string | X's stable numeric account identifier. Use it, rather than the handle, to identify the X account. |
| `twitter_handle` | string | Handle returned by X during the Owner's most recent connection or refresh. It can lag behind a later X-side rename. |


When present, `rewards` is an account rewards object:

#### AccountRewardsMsg

Cumulative reward totals received by an account.

| Field | Type | Description |
|---|---|---|
| `referral_rewards_received_usd` | decimal string, 6 d.p. | Cumulative referral rewards received. |
| `builder_fees_received_usd` | decimal string, 6 d.p. | Cumulative builder fees received. |
| `user_rewards_received_usd` | decimal string, 6 d.p. | Cumulative user rewards received. |


When present, `lifetime_stats` is an account lifetime stats object:

#### AccountLifetimeStatsMsg

Complete maker and taker lifetime trade totals for an account.

| Field | Type | Description |
|---|---|---|
| `maker` | [LifetimeStatsMsg](#lifetimestatsmsg) | Maker. |
| `taker` | [LifetimeStatsMsg](#lifetimestatsmsg) | Taker. |


Each `maker` and `taker` value is a liquidity-side lifetime stats object:

#### LifetimeStatsMsg

Lifetime trade totals for one account liquidity side.

| Field | Type | Description |
|---|---|---|
| `volume_contracts` | string | Whole contracts traded over the account's lifetime. |
| `weighted_volume` | string | (Optional) Lifetime weighted volume in fractional weighted contracts. Omitted until historical weighted volume is complete. |
| `volume_notional_usd` | string | Lifetime traded notional in decimal USD. |
| `fees_paid_usd` | string | Lifetime fees paid in decimal USD; maker rebates are negative. |


Every element in `positions` is a JSON object. See
[Realized and Unrealized PnL](general.txt#realized-and-unrealized-pnl) for position lifecycle,
average entry price, and PnL semantics:

#### PositionMsg

An account's current position in a market.

A position's lifecycle begins when the position becomes non-zero and ends when it touches or crosses zero.

| Field | Type | Description |
|---|---|---|
| `symbol` | string ([Symbol](#market-symbols)) | Symbol of the market this position is in. |
| `size` | i64 string | Signed position size. Positive for long, negative for short. |
| `cumulative_fees_usd` | signed decimal string, 6 d.p. | Signed cumulative fees paid for the current position. Positive values are fees paid; negative values are rebates. |
| `realized_pnl_usd` | signed decimal string, 6 d.p. | Cumulative realized PnL for the current position, excluding fees. PnL only realizes on closing trades. |
| `unrealized_pnl_usd` | signed decimal string, 6 d.p. | Unrealized PnL for the remaining open position, excluding fees. This is the amount of PnL that would be realized if the remaining position were closed at mark price. Equal to `size * (mark - entry)`. |
| `mark_price` | decimal string, 6 d.p. | Most recent mark price for the market. |
| `average_entry_price` | decimal string, 6 d.p. | (Optional) Average entry price rounded to 6dp. Not included if position size is zero. |
| `seq` | u64 string | The sequence number when this position was opened. Resets on touching zero. |
| `update_seq` | u64 string | The sequence number when this position last changed. Advances on every fill and resolution. |
| `open_ts_ms` | u64 string | When this position was opened. Resets on touching zero. |
| `update_ts_ms` | u64 string | When this position last changed. Advances on every fill and resolution. |


Every element in `pending_deposits` is a JSON object:

#### DepositMsg

Deposit lifecycle entry included in account updates.

| Field | Type | Description |
|---|---|---|
| `deposit_id` | u64 string | Unique identifier for this deposit lifecycle. |
| `owner` | base58 string | Account owner's wallet public key (Solana address). |
| `amount` | decimal string, 6 d.p. | Deposited amount in USD. |
| `transfer_status` | string enum: `"VERIFYING"`, `"PROCESSING"`, `"REJECTED"`, `"COMPLETED"` | Generic lifecycle state of this deposit. Deposits use `PROCESSING` or `COMPLETED`. |


Every element in `pending_withdrawals` is a JSON object:

#### PendingWithdrawalMsg

Pending withdrawal lifecycle item exposed by read API snapshots and WebSocket updates.

Snapshots contain active `VERIFYING` and `PROCESSING` withdrawals. WebSocket updates may also include terminal `REJECTED` or `COMPLETED` lifecycle updates so clients can remove the withdrawal from pending UI.

| Field | Type | Description |
|---|---|---|
| `owner` | base58 string | Account owner's wallet public key (Solana address). |
| `status` | string enum: `"VERIFYING"`, `"PROCESSING"`, `"REJECTED"`, `"COMPLETED"` | Current lifecycle state for this pending withdrawal. |
| `amount` | decimal string, 6 d.p. | Amount of collateral being withdrawn in USD. |
| `destination_authority` | base58 string | Solana wallet address that will receive the withdrawal. This is the owner/authority address, not the associated token account address. |
| `chain_seq` | u64 string | (Optional) Withdrawal transfer chain sequence. Present when `status` is `PROCESSING` or `COMPLETED`. |


```bash
curl 'https://data.pascal.trade/api/v1/accounts/GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB'
```

```json
{
  "status": "success",
  "data": {
    "username": "Trader",
    "twitter_account_connection": {
      "twitter_user_id": "1234567890",
      "twitter_handle": "pascaldottrade"
    },
    "collateral_usd": "100.000000",
    "rewards": {
      "referral_rewards_received_usd": "12.500000",
      "builder_fees_received_usd": "34.375000",
      "user_rewards_received_usd": "5.000000"
    },
    "lifetime_stats": {
      "maker": {
        "volume_contracts": "1250",
        "weighted_volume": "250.000000",
        "volume_notional_usd": "625.000000",
        "fees_paid_usd": "-0.625000"
      },
      "taker": {
        "volume_contracts": "750",
        "weighted_volume": "150.000000",
        "volume_notional_usd": "375.000000",
        "fees_paid_usd": "1.125000"
      }
    },
    "orders": [
      {
        "id": "987654321",
        "client_order_id": "42",
        "symbol": "SIM_EVENT_1.MARKET_1",
        "side": "BID",
        "price": "0.550000",
        "size_original": "10",
        "size_remaining": "7",
        "size_filled": "3",
        "notional_filled": "1.650000",
        "tif": "GTC",
        "type": "LIMIT",
        "post_only": false,
        "reduce_only": false,
        "seq": "67880",
        "update_seq": "67891",
        "place_ts_ms": "1731536000050",
        "update_ts_ms": "1731536000050"
      }
    ],
    "positions": [
      {
        "symbol": "SIM_EVENT_1.MARKET_1",
        "size": "3",
        "cumulative_fees_usd": "0.000742",
        "realized_pnl_usd": "0.000000",
        "unrealized_pnl_usd": "0.000000",
        "mark_price": "0.550000",
        "average_entry_price": "0.550000",
        "seq": "67880",
        "update_seq": "67891",
        "open_ts_ms": "1731535900000",
        "update_ts_ms": "1731536000050"
      }
    ],
    "pending_deposits": [
      {
        "deposit_id": "7",
        "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
        "amount": "100.000000",
        "transfer_status": "PROCESSING"
      }
    ],
    "pending_withdrawals": [
      {
        "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
        "status": "VERIFYING",
        "amount": "25.000000",
        "destination_authority": "29d2S7vB453rNYFdR5Ycwt7y9haRT5fwVwL9zTmBhfV2"
      }
    ]
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Trading Keys

`GET <read_base_url>/api/v1/accounts/{owner}/trading-keys`

Returns active trading keys for one account.

**JSON Response Payload**

Response `data` is an array of [TradingKeyMsg](#tradingkeymsg) objects.

```bash
curl 'https://data.pascal.trade/api/v1/accounts/GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB/trading-keys'
```

```json
{
  "status": "success",
  "data": [
    {
      "trading_key": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
      "name": "api-doc-key",
      "expiration_ts_ms": "1732140800000",
      "open_order_count": "2"
    }
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Trading Key Accounts

`GET <read_base_url>/api/v1/trading-keys/{trading_key_pubkey}/accounts`

Returns account owner addresses that have `{trading_key_pubkey}`
permissioned as an active trading key. One trading key can be assigned
to multiple accounts.

**JSON Response Payload**

Response `data` is an array of account owner addresses, encoded as base58
strings.

```bash
curl 'https://data.pascal.trade/api/v1/trading-keys/2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1/accounts'
```

```json
{
  "status": "success",
  "data": [
    "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB"
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Builder Stats

`GET <read_base_url>/api/v1/accounts/{owner}/builder-stats`

Returns lifetime statistics for fills from orders that named `owner` as
builder. Each fill contributes separately, so a trade contributes twice when
both orders name `owner`. Accounts never named as builder return zero totals.

**JSON Response Payload**

#### AccountBuilderStatsMsg

Account builder stats response: lifetime totals across fills of orders where this account was the builder.

| Field | Type | Description |
|---|---|---|
| `builder_volume_contracts` | u128 string | Total contracts across attributed fills. |
| `builder_volume_notional_usd` | decimal string, 6 d.p. | Sum of size × price across attributed fills. |
| `builder_fee_base_usd` | decimal string, 6 d.p. | Sum of size × price × (1 − price), rounded per fill. At a constant rate r, fees equal r × this value, up to per-fill rounding. |
| `builder_fees_received_usd` | decimal string, 6 d.p. | Builder fees received, credited to free collateral at settlement. |


```bash
curl 'https://data.pascal.trade/api/v1/accounts/GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB/builder-stats'
```

```json
{
  "status": "success",
  "data": {
    "builder_volume_contracts": "12500",
    "builder_volume_notional_usd": "6875.000000",
    "builder_fee_base_usd": "3093.750000",
    "builder_fees_received_usd": "34.375000"
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Taker Discount Terms

`GET <read_base_url>/api/v1/accounts/{owner}/taker-discount-terms`

Returns the stored taker discount terms and fee-savings usage for `owner`.

`taker_discount_terms` is absent when the owner has no stored terms. Stored
terms discount the owner's taker fees by `taker_fee_discount_share` until
`fee_savings_usd` crosses `fee_savings_limit_usd`; later taker fills receive no
discount. See the [Referral Program](general.txt#referral-program) for the terms applied
through referral attribution.

**JSON Response Payload**

#### AccountTakerDiscountTermsMsg

Account taker discount terms response. `taker_discount_terms` is absent when the owner has no stored terms.

| Field | Type | Description |
|---|---|---|
| `taker_discount_terms` | [TakerDiscountTermsMsg](#takerdiscounttermsmsg) | (Optional) The owner's stored terms; absent when the owner has none. |


`taker_discount_terms`, when present, is a JSON object:

#### TakerDiscountTermsMsg

Stored taker discount terms and fee-savings usage for one owner.

| Field | Type | Description |
|---|---|---|
| `taker_fee_discount_share` | decimal string, 6 d.p. | Fraction of the taker fee discounted while the fee-savings cap is not exhausted. |
| `created_ts_ms` | u64 string | Timestamp when these terms were created, in milliseconds since the Unix epoch. |
| `fee_savings_limit_usd` | decimal string, 6 d.p. | Maximum taker fee savings this owner can receive through these terms. |
| `fee_savings_usd` | decimal string, 6 d.p. | Cumulative taker fee savings. The discount stops after this crosses the limit. |


```bash
curl 'https://data.pascal.trade/api/v1/accounts/GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB/taker-discount-terms'
```

```json
{
  "status": "success",
  "data": {
    "taker_discount_terms": {
      "taker_fee_discount_share": "0.050000",
      "created_ts_ms": "1731535900000",
      "fee_savings_limit_usd": "250.000000",
      "fee_savings_usd": "12.500000"
    }
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Referrals

`GET <read_base_url>/api/v1/accounts/{owner}/referrals`

Returns up to the 500 most recently created Referrals for which
`{owner}` is the Reward Owner: one entry per referred user, with the reward paid so far and the
reward-paid cap. Referrals are included identically regardless of their original attribution
mechanism.

The response includes the owner's Generated and Custom Referral Codes and whether the Custom Code
has been revoked. `can_generate_referral_code` and `can_claim_custom_referral_code` report whether
the corresponding signed write requests would currently succeed; a submitted Custom Code may
still be unavailable.

`referral_reward_terms` is the terms applied to Referrals created for this owner in the future.
Each existing Referral keeps the share and cap fixed when it was created. A Referral pays rewards
until `reward_paid_usd` crosses `reward_paid_limit_usd`; later fills pay no reward. See the
[Referral Program](general.txt#referral-program) for the current terms.

**JSON Response Payload**

#### OwnerReferralsMsg

Owner referrals response.

| Field | Type | Description |
|---|---|---|
| `referral_reward_terms` | [ReferralRewardTermsMsg](#referralrewardtermsmsg) | Terms applied to Referrals created for this owner in the future. Existing Referrals keep the share and limit fixed when they were created. |
| `reward_paid_total_usd` | decimal string, 6 d.p. | Total reward paid to this owner across all their Referrals. |
| `referral_count_total` | integer | Total number of this owner's Referrals, including any omitted from `referrals` by an endpoint response limit. |
| `referrals` | array of [ReferralMsg](#referralmsg) | This owner's Referrals as Reward Owner, one per referred owner, newest first. |
| `generated_referral_code` | string | (Optional) This owner's Generated Referral Code, if they have created one. |
| `custom_referral_code` | string | (Optional) This owner's Custom Referral Code, including a revoked code retained for support context. |
| `custom_referral_code_revoked` | boolean | Whether `custom_referral_code` has been revoked and no longer resolves for attribution. |
| `can_generate_referral_code` | boolean | Whether a generate-referral-code request from this owner would currently succeed: Referral Codes are enabled, the owner has deposited, no Generated Code exists, and no active Custom Code exists. |
| `can_claim_custom_referral_code` | boolean | Whether the owner may currently claim a Custom Referral Code. The submitted code may still be unavailable. |


`referral_reward_terms` is a JSON object:

#### ReferralRewardTermsMsg

Reward terms applied to a Reward Owner's future Referrals.

| Field | Type | Description |
|---|---|---|
| `referral_reward_share` | decimal string, 6 d.p. | Fraction of the venue fee from each referred taker fill paid to the Reward Owner. |
| `per_referred_owner_reward_paid_limit_usd` | decimal string, 6 d.p. | Maximum reward paid to the Reward Owner for a single Referred Owner. |


Every element in `referrals` is a JSON object:

#### ReferralMsg

One Referral from its Reward Owner's perspective.

| Field | Type | Description |
|---|---|---|
| `seq` | `ReferralSeq` | Monotonic referral creation sequence for stable ordering and future pagination. |
| `referred_owner` | base58 string | Owner whose registration created this Referral. |
| `created_ts_ms` | u64 string | Timestamp when the Referral was created, in milliseconds since the Unix epoch. |
| `referral_reward_share` | decimal string, 6 d.p. | Reward share fixed when the Referral was created. |
| `reward_paid_usd` | decimal string, 6 d.p. | Cumulative reward paid to the Reward Owner for this Referral. Rewards stop after this crosses the limit. |
| `reward_paid_limit_usd` | decimal string, 6 d.p. | Maximum reward paid to the Reward Owner for this Referral. |


```bash
curl 'https://data.pascal.trade/api/v1/accounts/GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB/referrals'
```

```json
{
  "status": "success",
  "data": {
    "referral_reward_terms": {
      "referral_reward_share": "0.100000",
      "per_referred_owner_reward_paid_limit_usd": "10000.000000"
    },
    "reward_paid_total_usd": "25.000000",
    "referral_count_total": 1,
    "referrals": [
      {
        "seq": "42",
        "referred_owner": "J2xccRtuG43drESLYznHhLhQkLTdfepcKYbiQ9BsJVaf",
        "created_ts_ms": "1731535900000",
        "referral_reward_share": "0.100000",
        "reward_paid_usd": "25.000000",
        "reward_paid_limit_usd": "10000.000000"
      }
    ],
    "generated_referral_code": "k7wq2m4x",
    "custom_referral_code": "trader1",
    "custom_referral_code_revoked": false,
    "can_generate_referral_code": false,
    "can_claim_custom_referral_code": false
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Deposit Address

`GET <read_base_url>/api/v1/accounts/{owner}/deposit-address`

Returns the wallet-facing deposit address for one account.

**JSON Response Payload**

#### DepositAddressMsg

Wallet-facing deposit address data for a user owner.

| Field | Type | Description |
|---|---|---|
| `owner` | base58 string | The account owner. |
| `deposit_address` | base58 string | (Optional) The deposit address PDA corresponding to the account owner. Present only after the account has registered a deposit address, and immutable once set. |
| `registered` | boolean | Whether the deposit address is registered. |


```bash
curl 'https://data.pascal.trade/api/v1/accounts/GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB/deposit-address'
```

```json
{
  "status": "success",
  "data": {
    "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "deposit_address": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
    "registered": true
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Fill History

`GET <read_base_url>/api/v1/accounts/{owner}/fills`

Returns fill history for one account, optionally filtered by up to
50 symbols.

**Query Parameters**

| Field | Type | Description |
|---|---|---|
| `symbols` | comma-separated array of string ([Symbol](#market-symbols)) | (Optional) Comma-delimited list of market symbols to filter by. Empty returns fills for all markets. |
| `before_cursor` | string | (Optional) Opaque cursor returned as `next_cursor` from a prior page. Results are strictly older than this cursor. |
| `at_or_before_seq` | u64 string | (Optional) Inclusive sequence number to start pagination from. Use this when you have an event (eg a fill or order) and want to start pagination from that event. After you get the first page, use the `next_cursor` to continue. |
| `limit` | integer | (Optional) Maximum number of items to return. |


**JSON Response Payload**

Returns a paginated JSON object:

| Field | Type | Description |
|---|---|---|
| `items` | array of [FillMsg](#fillmsg) | Result page items. |
| `next_cursor` | string | (Optional) Cursor for the next page of results. Omitted on the last page. |


```bash
curl 'https://data.pascal.trade/api/v1/accounts/GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB/fills?symbols=SIM_EVENT_1.MARKET_1&limit=50'
```

```json
{
  "status": "success",
  "data": {
    "items": [
      {
        "trade_id": "555001",
        "symbol": "SIM_EVENT_1.MARKET_1",
        "side": "BID",
        "fill_price": "0.550000",
        "fill_size": "3",
        "liquidity": "TAKER",
        "order_id": "987654321",
        "client_order_id": "42",
        "fee_usd": "0.000742",
        "collateral_change_usd": "-1.650742",
        "position_size_prev": "0",
        "realized_pnl_usd": "0.000000",
        "position_open_seq": "67891",
        "position_open_ts_ms": "1731536000050",
        "seq": "67891",
        "trade_ts_ms": "1731536000050"
      }
    ]
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Transfer History

`GET <read_base_url>/api/v1/accounts/{owner}/transfers`

Returns transfer (deposit and withdrawal) history for one account.

**Query Parameters**

| Field | Type | Description |
|---|---|---|
| `before_cursor` | string | (Optional) Opaque cursor returned as `next_cursor` from a prior page. Results are strictly older than this cursor. |
| `at_or_before_seq` | u64 string | (Optional) Inclusive sequence number to start pagination from. Use this when you have an event (eg a fill or order) and want to start pagination from that event. After you get the first page, use the `next_cursor` to continue. |
| `limit` | integer | (Optional) Maximum number of items to return. |


**JSON Response Payload**

Returns a paginated JSON object:

| Field | Type | Description |
|---|---|---|
| `items` | array of [TransferMsg](#transfermsg) | Result page items. |
| `next_cursor` | string | (Optional) Cursor for the next page of results. Omitted on the last page. |


Every element in `items` is a JSON object:

#### TransferMsg

Transfer ledger entry included in account updates.

| Field | Type | Description |
|---|---|---|
| `type` | string enum: `"DEPOSIT"`, `"WITHDRAWAL"`, `"REWARD"` | Kind of balance movement: deposit, withdrawal, or user reward. |
| `status` | string enum: `"VERIFYING"`, `"PROCESSING"`, `"REJECTED"`, `"COMPLETED"` | Current user-facing lifecycle state for this transfer. |
| `collateral_change_usd` | signed decimal string, 6 d.p. | Net change to account collateral from this transfer. |
| `fee_usd` | signed decimal string, 6 d.p. | Transfer fee paid by the user. Positive values are fees paid. |
| `net_usd` | signed decimal string, 6 d.p. | Signed balance movement after fees. |
| `seq` | u64 string | Sequence number where account collateral was updated. |
| `transfer_ts_ms` | u64 string | Timestamp when account collateral was updated. |
| `chain_seq` | u64 string | (Optional) Chain sequence used to correlate withdrawal lifecycle updates. Present only for withdrawal transfers. |
| `user_reward_reason` | string | (Optional) Product reason for a user reward. Absent for deposits and withdrawals. |


```bash
curl 'https://data.pascal.trade/api/v1/accounts/GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB/transfers?limit=50'
```

```json
{
  "status": "success",
  "data": {
    "items": [
      {
        "type": "DEPOSIT",
        "status": "COMPLETED",
        "collateral_change_usd": "100.000000",
        "fee_usd": "0.000000",
        "net_usd": "100.000000",
        "seq": "67880",
        "transfer_ts_ms": "1731535900000"
      }
    ]
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Position Resolution History

`GET <read_base_url>/api/v1/accounts/{owner}/position-resolutions`

Returns historical position-resolution payouts for one account.

**Query Parameters**

| Field | Type | Description |
|---|---|---|
| `before_cursor` | string | (Optional) Opaque cursor returned as `next_cursor` from a prior page. Results are strictly older than this cursor. |
| `at_or_before_seq` | u64 string | (Optional) Inclusive sequence number to start pagination from. Use this when you have an event (eg a fill or order) and want to start pagination from that event. After you get the first page, use the `next_cursor` to continue. |
| `limit` | integer | (Optional) Maximum number of items to return. |


**JSON Response Payload**

Returns a paginated JSON object:

| Field | Type | Description |
|---|---|---|
| `items` | array of [PositionResolutionMsg](#positionresolutionmsg) | Result page items. |
| `next_cursor` | string | (Optional) Cursor for the next page of results. Omitted on the last page. |


Every element in `items` is a JSON object:

#### PositionResolutionMsg

Resolution message for API responses.

| Field | Type | Description |
|---|---|---|
| `symbol` | string ([Symbol](#market-symbols)) | Market symbol for the resolved position. |
| `resolution` | decimal string, 6 d.p. | Final settlement price in dollars. |
| `size` | i64 string | Signed position size settled by this resolution. |
| `collateral_change_usd` | decimal string, 6 d.p. | Net collateral change from settling this position. |
| `realized_pnl_usd` | signed decimal string, 6 d.p. | Realized PnL from this resolution, excluding fees. |
| `position_open_seq` | u64 string | (Optional) Opening sequence of the position settled by this resolution. |
| `position_open_ts_ms` | u64 string | (Optional) Opening timestamp, in milliseconds since the Unix epoch, of the position settled by this resolution. |
| `seq` | u64 string | Matching engine sequence number when this resolution was applied. |
| `position_resolution_ts_ms` | u64 string | Timestamp when this position was resolved, in milliseconds since the Unix epoch. |


```bash
curl 'https://data.pascal.trade/api/v1/accounts/GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB/position-resolutions?limit=50'
```

```json
{
  "status": "success",
  "data": {
    "items": [
      {
        "symbol": "SIM_EVENT_1.MARKET_1",
        "resolution": "1.000000",
        "size": "3",
        "collateral_change_usd": "3.000000",
        "realized_pnl_usd": "1.350000",
        "position_open_seq": "67891",
        "position_open_ts_ms": "1731536000050",
        "seq": "67891",
        "position_resolution_ts_ms": "1731536000050"
      }
    ]
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### PnL History

`GET <read_base_url>/api/v1/accounts/{owner}/history`

Returns account value and PnL time series for one account.

Historical windows are `day` (30m), `week` (4h), `month` (12h), and `all_time` (24h).

**JSON Response Payload**

| Field | Type | Description |
|---|---|---|
| `items` | array of [AccountHistoryTimeseries](#accounthistorytimeseries) | Account value and PnL series, one entry per standard timeframe. |


Every element in `items` is a JSON object:

#### AccountHistoryTimeseries

Account history series for one timeframe.

| Field | Type | Description |
|---|---|---|
| `timeframe` | string enum: `"day"`, `"week"`, `"month"`, `"all_time"` | Chart lookback window for this series. |
| `data` | [AccountHistoryTimeseriesData](#accounthistorytimeseriesdata) | Sampled account value and PnL points for this timeframe. |


`data` object:

#### AccountHistoryTimeseriesData

Chart lines for account history.

| Field | Type | Description |
|---|---|---|
| `account_value_history` | array of [TimeseriesPoint](#timeseriespoint) | Sampled total account value over time. |
| `trading_pnl_history` | array of [TimeseriesPoint](#timeseriespoint) | Sampled cumulative trading PnL, excluding rewards received. |
| `referral_rewards_received_history` | array of [TimeseriesPoint](#timeseriespoint) | Sampled cumulative referral rewards received. |
| `builder_fees_received_history` | array of [TimeseriesPoint](#timeseriespoint) | Sampled cumulative builder fees received. |


Every value in an account-history series is a two-element array
`[timestamp_ms, decimal_string]`:

#### TimeseriesPoint

One chart point, serialized as `[timestamp_ms, decimal_string]`.

| Field | Type | Description |
|---|---|---|
| `0` | u64 string | Timestamp in milliseconds. |
| `1` | string | Decimal string value. |


```bash
curl 'https://data.pascal.trade/api/v1/accounts/GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB/history'
```

```json
{
  "status": "success",
  "data": {
    "items": [
      {
        "timeframe": "day",
        "data": {
          "account_value_history": [
            [
              "1731536000000",
              "1000.000000"
            ]
          ],
          "trading_pnl_history": [
            [
              "1731536000000",
              "20.000000"
            ]
          ],
          "referral_rewards_received_history": [
            [
              "1731536000000",
              "3.000000"
            ]
          ],
          "builder_fees_received_history": [
            [
              "1731536000000",
              "2.000000"
            ]
          ]
        }
      }
    ]
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

## Market Data WebSocket

`GET <ws_base_url>` upgrades to a WebSocket connection. Clients send JSON text frames.

The server allows up to 10,000 concurrent connections
and 5,000 subscriptions per connection.

### Client Messages

Clients send JSON text frames. There are three message types: `subscribe`,
`unsubscribe`, and `ping`.

**Subscribe** to one or more channels. The server responds with a `snapshot`
on each channel, followed by `update` messages as state changes.

```json
{
  "type": "subscribe",
  "channels": [
    {
      "channel": "book",
      "symbol": "SIM_EVENT_1.MARKET_1"
    },
    {
      "channel": "trades",
      "symbol": "SIM_EVENT_1.MARKET_1"
    },
    {
      "channel": "all_trades"
    }
  ]
}
```

**Unsubscribe** uses the same shape with `type: "unsubscribe"`.

```json
{
  "type": "unsubscribe",
  "channels": [
    {
      "channel": "book",
      "symbol": "SIM_EVENT_1.MARKET_1"
    }
  ]
}
```

**Ping** keeps the connection alive. The server responds with the literal
frame `{"type":"pong"}`.

```json
{
  "type": "ping"
}
```

#### Channels

Each entry in `channels` is one of:

```json
{"channel": "book",    "symbol": "<market symbol>"}
{"channel": "trades",  "symbol": "<market symbol>"}
{"channel": "candles", "symbol": "<market symbol>", "interval": "1m"}
{"channel": "mark_price_candles", "symbol": "<market symbol>", "interval": "1m"}
{"channel": "account", "owner":  "<wallet base58>"}
{"channel": "market_update"}
```

- `book`: order book snapshots and price-level updates for one market.
- `trades`: trades for one market.
- `candles`: current in-progress candle for one market and interval;
  `interval` must be one of `1m`, `5m`, `15m`, `1h`, `4h`, `12h`, and `1d`.
- `mark_price_candles`: current in-progress mark price candle for one market and interval;
  `interval` must be one of `1m`, `5m`, `15m`, `1h`, `4h`, `12h`, and `1d`.
- `account`: live account updates for one wallet.
- `market_update`: market listings and updates.

### Server Messages

For each subscribed channel, the server emits a `snapshot` message followed by `update`
messages whenever the channel state changes. Error messages flatten the channel descriptor
with `type: "error"` and error fields.

**Message type enum**

#### WsMessageType

Type of WebSocket message sent to clients.

| Value | Description |
|---|---|
| `"snapshot"` | A snapshot message is sent when a client first subscribes. |
| `"update"` | An update message is sent when channel state changes. |
| `"error"` | An error message reports a client- or channel-level failure. It may be sent in response to a malformed or rejected request, or emitted later for a subscribed channel that can no longer be served. |


**Shared server context fields**

| Field | Type | Description |
|---|---|---|
| `seq` | u64 string | (Optional) Matching engine sequence number. Not present if the request is rejected before reaching the matching engine, for example due to invalid request data. |
| `state_time_ms` | u64 string | (Optional) Matching engine timestamp as of the last matching round. Not present if the request is rejected before reaching the matching engine, for example due to invalid request data. |
| `server_time_ms` | u64 string | API server timestamp when this result was produced. Requests in a batch request can resolve at different times, so items in one response may carry different timestamps. |


**Error data object**

| Field | Type | Description |
|---|---|---|
| `code` | [ApiErrorCode](#apierrorcode) | Stable, machine-readable error code. |
| `message` | string | Human-readable error message. May evolve over time. For debugging and display only. |


```json
{
  "channel": "book",
  "symbol": "SIM_EVENT_1.MARKET_1",
  "type": "error",
  "data": {
    "code": "SYMBOL_NOT_FOUND",
    "message": "symbol not found: symbol=SIM_EVENT_1.MARKET_1"
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Book Channel

L2 book feed for one market.

The first message after subscription is always a `snapshot` message
with the full order book state and [market spec](#marketspec).

Subsequent messages are `update`s which include price level changes
(level removals are represented with `size = 0`) and any changes to
the market spec.

**Channel Descriptor**

| Field | Type | Description |
|---|---|---|
| `channel` | string literal `"book"` | Channel discriminator. |
| `symbol` | string ([Symbol](#market-symbols)) | Market symbol to stream order book updates for. |


**JSON Message Payload**

Payload uses [OrderBookMsg](#orderbookmsg).

```json
{
  "channel": "book",
  "symbol": "SIM_EVENT_1.MARKET_1",
  "type": "snapshot",
  "data": {
    "asks": [
      [
        "0.560000",
        "12"
      ],
      [
        "0.570000",
        "20"
      ]
    ],
    "bids": [
      [
        "0.540000",
        "15"
      ],
      [
        "0.530000",
        "7"
      ]
    ],
    "spec": {
      "symbol": "SIM_EVENT_1.MARKET_1",
      "taker_fee_rate": "0.001000",
      "maker_rebate_share": "0.500000",
      "tick_size_min": "0.010000",
      "tick_sig_figs": 2
    }
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

```json
{
  "channel": "book",
  "symbol": "SIM_EVENT_1.MARKET_1",
  "type": "update",
  "data": {
    "asks": [
      [
        "0.570000",
        "0"
      ]
    ],
    "bids": [
      [
        "0.540000",
        "15"
      ]
    ]
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Trades Channel

Trades for one market.

**Channel Descriptor**

| Field | Type | Description |
|---|---|---|
| `channel` | string literal `"trades"` | Channel discriminator. |
| `symbol` | string ([Symbol](#market-symbols)) | Market symbol to stream public trades for. |


**JSON Message Payload**

`data` is a JSON array of trade objects. Every element in the array is a
JSON object using [PublicTradeMsg](#publictrademsg).

```json
{
  "channel": "trades",
  "symbol": "SIM_EVENT_1.MARKET_1",
  "type": "update",
  "data": [
    {
      "trade_id": "555001",
      "symbol": "SIM_EVENT_1.MARKET_1",
      "taker_side": "BID",
      "price": "0.550000",
      "size": "3",
      "maker": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
      "taker": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
      "seq": "67891",
      "trade_ts_ms": "1731536000050"
    }
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### All Trades Channel

Recent public trades across all markets. The initial `snapshot` contains up to
100 recent trades. Subsequent `update`
messages contain every new trade since the last update.

Snapshots and updates are ordered chronologically, oldest first.

**Channel Descriptor**

| Field | Type | Description |
|---|---|---|
| `channel` | string literal `"all_trades"` | Channel discriminator. |


**JSON Message Payload**

`data` is a JSON array of trade objects. Every element in the array is a
JSON object using [PublicTradeMsg](#publictrademsg).

```json
{
  "channel": "all_trades",
  "type": "snapshot",
  "data": [
    {
      "trade_id": "555001",
      "symbol": "SIM_EVENT_1.MARKET_1",
      "taker_side": "BID",
      "price": "0.550000",
      "size": "3",
      "maker": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
      "taker": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
      "seq": "67891",
      "trade_ts_ms": "1731536000050"
    }
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

```json
{
  "channel": "all_trades",
  "type": "update",
  "data": [
    {
      "trade_id": "555001",
      "symbol": "SIM_EVENT_1.MARKET_1",
      "taker_side": "BID",
      "price": "0.550000",
      "size": "3",
      "maker": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
      "taker": "2KW2XRd9kwqet15Aha2oK3tYvd3nWbTFH1MBiRAv1BE1",
      "seq": "67891",
      "trade_ts_ms": "1731536000050"
    }
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Candles Channel

Current in-progress candle for one market and interval.

**Channel Descriptor**

| Field | Type | Description |
|---|---|---|
| `channel` | string literal `"candles"` | Channel discriminator. |
| `symbol` | string ([Symbol](#market-symbols)) | Market symbol to stream candles for. |
| `interval` | string enum: `"1m"`, `"5m"`, `"15m"`, `"1h"`, `"4h"`, `"12h"`, `"1d"` | Candle aggregation interval. |


**JSON Message Payload**

`data` is a JSON array of candle objects. Every element in the array uses
[CandleMsg](#candlemsg).

```json
{
  "channel": "candles",
  "symbol": "SIM_EVENT_1.MARKET_1",
  "interval": "1m",
  "type": "update",
  "data": [
    {
      "time": "1731535960000",
      "open": "0.520000",
      "high": "0.570000",
      "low": "0.510000",
      "close": "0.550000",
      "volume": "120",
      "taker_buy_volume": "70",
      "taker_sell_volume": "50",
      "volume_notional": "66.000000",
      "taker_buy_volume_notional": "38.500000",
      "taker_sell_volume_notional": "27.500000",
      "trade_count": "8",
      "taker_buy_count": "5",
      "taker_sell_count": "3"
    }
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Mark Price Candles Channel

Current in-progress mark price candle for one market and interval.

**Channel Descriptor**

| Field | Type | Description |
|---|---|---|
| `channel` | string literal `"mark_price_candles"` | Channel discriminator. |
| `symbol` | string ([Symbol](#market-symbols)) | Market symbol to stream mark price candles for. |
| `interval` | string enum: `"1m"`, `"5m"`, `"15m"`, `"1h"`, `"4h"`, `"12h"`, `"1d"` | Candle aggregation interval. |


**JSON Message Payload**

`data` is a JSON array of mark price candle objects. Every element in the array uses
[MarkPriceCandleMsg](#markpricecandlemsg).

```json
{
  "channel": "mark_price_candles",
  "symbol": "SIM_EVENT_1.MARKET_1",
  "interval": "1m",
  "type": "update",
  "data": [
    {
      "time": "1731535960000",
      "open": "0.540000",
      "high": "0.580000",
      "low": "0.530000",
      "close": "0.560000"
    }
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

### Account Channel

Live account updates for one account.

The first message after subscription is always a `snapshot` message, containing the
same fields as the [Account State Snapshot](#account-state-snapshot).

Subsequent `update` messages only populate fields which have changed since the most
recent message. For example, if you cancel an order, you will see one update inside
the `orders` array, and no other fields. If an order fills, you will see an update
with changes in `orders`, `positions`, and `collateral_usd`.

We chose this consolidated shape to make it easy for consumers to atomically register
updates to the account state.

**Channel Descriptor**

| Field | Type | Description |
|---|---|---|
| `channel` | string literal `"account"` | Channel discriminator. |
| `owner` | base58 string | Account owner's wallet public key (Solana address). |
| `exclude_orders` | boolean | (Optional) When true, the initial snapshot contains an empty `orders` array and subsequent order updates are not sent. Defaults to false. |


**JSON Message Payload**

| Field | Type | Description |
|---|---|---|
| `username` | `Username` | (Optional) Owner-chosen handle. Present in REST responses and WebSocket subscription snapshots when set; always omitted from incremental WebSocket updates. |
| `twitter_account_connection` | [TwitterAccountConnection](#twitteraccountconnection) | (Optional) Twitter account connected to the owner. Present in REST responses and WebSocket subscription snapshots when connected; always omitted from incremental WebSocket updates. |
| `collateral_usd` | decimal string, 6 d.p. | (Optional) Current free collateral in USD. The account WebSocket channel omits this field when there has been no collateral change since the last snapshot. |
| `rewards` | [AccountRewardsMsg](#accountrewardsmsg) | (Optional) Complete cumulative account reward totals. Present in REST and WebSocket snapshots. The account WebSocket channel omits this field when no reward component changed since the last snapshot. |
| `lifetime_stats` | [AccountLifetimeStatsMsg](#accountlifetimestatsmsg) | (Optional) Complete account lifetime trade totals. Omitted if data is not available. The account WebSocket channel also omits this field when no trade has changed the totals since the last snapshot. |
| `orders` | array of [OrderMsg](#ordermsg) | Open orders for this account, or all changed orders when used on the account WebSocket channel. |
| `positions` | array of [PositionMsg](#positionmsg) | Current open positions for this account, or all changed positions when used on the account WebSocket channel. |
| `pending_deposits` | array of [DepositMsg](#depositmsg) | Deposits being processed onchain but not yet credited. |
| `pending_withdrawals` | array of [PendingWithdrawalMsg](#pendingwithdrawalmsg) | Active pending withdrawals. |
| `fills` | array of [FillMsg](#fillmsg) | (Optional) Fills since the last snapshot or update. Omitted when no fills occurred. |
| `resolutions` | array of [PositionResolutionMsg](#positionresolutionmsg) | (Optional) Position resolutions since the last snapshot or update. Omitted when no resolutions occurred. |
| `closed_positions` | array of [PositionHistoryMsg](#positionhistorymsg) | (Optional) Completed position instances since the last snapshot or update, newest close first. Includes full closes, direction flips, and market resolutions. Each item has `position_instance_count` equal to `"1"`. Omitted from snapshots and updates with no closes. |
| `transfers` | array of [TransferMsg](#transfermsg) | (Optional) Balance transfers since the last snapshot or update. Omitted when no transfers occurred. |


```json
{
  "channel": "account",
  "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
  "type": "update",
  "data": {
    "collateral_usd": "100.000000",
    "rewards": {
      "referral_rewards_received_usd": "12.500000",
      "builder_fees_received_usd": "34.375000",
      "user_rewards_received_usd": "5.000000"
    },
    "lifetime_stats": {
      "maker": {
        "volume_contracts": "1250",
        "weighted_volume": "250.000000",
        "volume_notional_usd": "625.000000",
        "fees_paid_usd": "-0.625000"
      },
      "taker": {
        "volume_contracts": "750",
        "weighted_volume": "150.000000",
        "volume_notional_usd": "375.000000",
        "fees_paid_usd": "1.125000"
      }
    },
    "orders": [
      {
        "id": "987654321",
        "client_order_id": "42",
        "symbol": "SIM_EVENT_1.MARKET_1",
        "side": "BID",
        "price": "0.550000",
        "size_original": "10",
        "size_remaining": "7",
        "size_filled": "3",
        "notional_filled": "1.650000",
        "tif": "GTC",
        "type": "LIMIT",
        "post_only": false,
        "reduce_only": false,
        "seq": "67880",
        "update_seq": "67891",
        "place_ts_ms": "1731536000050",
        "update_ts_ms": "1731536000050"
      }
    ],
    "positions": [
      {
        "symbol": "SIM_EVENT_1.MARKET_1",
        "size": "3",
        "cumulative_fees_usd": "0.000742",
        "realized_pnl_usd": "0.000000",
        "unrealized_pnl_usd": "0.000000",
        "mark_price": "0.550000",
        "average_entry_price": "0.550000",
        "seq": "67880",
        "update_seq": "67891",
        "open_ts_ms": "1731535900000",
        "update_ts_ms": "1731536000050"
      }
    ],
    "pending_deposits": [
      {
        "deposit_id": "7",
        "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
        "amount": "100.000000",
        "transfer_status": "PROCESSING"
      }
    ],
    "pending_withdrawals": [
      {
        "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
        "status": "VERIFYING",
        "amount": "25.000000",
        "destination_authority": "29d2S7vB453rNYFdR5Ycwt7y9haRT5fwVwL9zTmBhfV2"
      }
    ],
    "fills": [
      {
        "trade_id": "555001",
        "symbol": "SIM_EVENT_1.MARKET_1",
        "side": "BID",
        "fill_price": "0.550000",
        "fill_size": "3",
        "liquidity": "TAKER",
        "order_id": "987654321",
        "client_order_id": "42",
        "fee_usd": "0.000742",
        "collateral_change_usd": "-1.650742",
        "position_size_prev": "0",
        "realized_pnl_usd": "0.000000",
        "position_open_seq": "67891",
        "position_open_ts_ms": "1731536000050",
        "seq": "67891",
        "trade_ts_ms": "1731536000050"
      }
    ],
    "transfers": [
      {
        "type": "DEPOSIT",
        "status": "COMPLETED",
        "collateral_change_usd": "100.000000",
        "fee_usd": "0.000000",
        "net_usd": "100.000000",
        "seq": "67880",
        "transfer_ts_ms": "1731535900000"
      }
    ]
  },
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

**Closed position instances**

When a position fully closes, flips direction, or resolves, `closed_positions`
contains its complete history row. Partial reductions continue updating `positions`.
A direction flip completes the old instance and updates `positions` with the new
instance in the same message. An update can contain multiple completed instances
for the same market.

Each entry uses the same format as
`GET /api/v1/accounts/{owner}/position-instances`, with `position_instance_count`
equal to `"1"`. Contract totals and average entry and exit prices cover the entire
instance. Realized PnL excludes fees. Entries are ordered by `close_seq` descending.

#### PositionHistoryMsg

Historical performance for one position instance or a group of position instances with the same market and side.

| Field | Type | Description |
|---|---|---|
| `symbol` | string ([Symbol](#market-symbols)) | Market symbol. |
| `position_side` | string enum: `"LONG"`, `"SHORT"` | Direction of the position instance. |
| `position_instance_count` | string | Number of position instances. This is `"1"` for a single position instance. |
| `held_until_resolution` | boolean | Whether the position instance was held until market resolution. For a position aggregate, this describes the most recently closed position instance. |
| `realized_pnl_usd` | string | Gross realized PnL, excluding fees, in decimal USD. |
| `cumulative_increasing_contracts` | string | Total contracts used to increase the position. |
| `cumulative_increasing_notional_usd` | string | Total notional used to increase the position, in decimal USD. |
| `cumulative_reducing_notional_usd` | string | Total notional used to reduce the position, in decimal USD. |
| `average_increasing_price` | decimal string, 6 d.p. | Contract-weighted average price used to increase the position, floored to 6 decimal places. |
| `average_reducing_price` | decimal string, 6 d.p. | Contract-weighted average price used to reduce the position, floored to 6 decimal places. |
| `open_seq` | u64 string | Sequence when the position instance opened. For a position aggregate, this is the earliest opening sequence. |
| `open_ts_ms` | u64 string | Timestamp when the position instance opened. For a position aggregate, this is the earliest opening timestamp. |
| `close_seq` | u64 string | Sequence when the position instance closed. For a position aggregate, this is the latest closing sequence. |
| `close_ts_ms` | u64 string | Timestamp when the position instance closed. For a position aggregate, this is the latest closing timestamp. |


The following example shows a 3-contract long entered at $0.55 and resolved at
$1.00. The completed instance has $1.35 of realized PnL, while `positions` reports
zero size and `resolutions` records the settlement.

```json
{
  "channel": "account",
  "owner": "GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",
  "type": "update",
  "data": {
    "collateral_usd": "101.349258",
    "orders": [],
    "positions": [
      {
        "symbol": "SIM_EVENT_1.MARKET_1",
        "size": "0",
        "cumulative_fees_usd": "0.000000",
        "realized_pnl_usd": "0.000000",
        "unrealized_pnl_usd": "0.000000",
        "mark_price": "1.000000",
        "seq": "67891",
        "update_seq": "67892",
        "open_ts_ms": "1731536000050",
        "update_ts_ms": "1731536000100"
      }
    ],
    "pending_deposits": [],
    "pending_withdrawals": [],
    "resolutions": [
      {
        "symbol": "SIM_EVENT_1.MARKET_1",
        "resolution": "1.000000",
        "size": "3",
        "collateral_change_usd": "3.000000",
        "realized_pnl_usd": "1.350000",
        "position_open_seq": "67891",
        "position_open_ts_ms": "1731536000050",
        "seq": "67892",
        "position_resolution_ts_ms": "1731536000100"
      }
    ],
    "closed_positions": [
      {
        "symbol": "SIM_EVENT_1.MARKET_1",
        "position_side": "LONG",
        "position_instance_count": "1",
        "held_until_resolution": true,
        "realized_pnl_usd": "1.350000",
        "cumulative_increasing_contracts": "3",
        "cumulative_increasing_notional_usd": "1.650000",
        "cumulative_reducing_notional_usd": "3.000000",
        "average_increasing_price": "0.550000",
        "average_reducing_price": "1.000000",
        "open_seq": "67891",
        "open_ts_ms": "1731536000050",
        "close_seq": "67892",
        "close_ts_ms": "1731536000100"
      }
    ]
  },
  "seq": "67892",
  "state_time_ms": "1731536000100",
  "server_time_ms": "1731536000123"
}
```

### Market Update Channel

Listings and updates for all markets.

The initial `snapshot` message contains an empty `data` payload; you may retrieve all markets via the GET /api/v1/markets endpoint. In order to guarantee your markets list is up to date, you may perform the following initialization process:

1. Subscribe to the market_update websocket channel.
2. Upon receiving the first message in the channel, request from the GET /api/v1/markets endpoint.
3. Cache all updates from the websocket locally.
4. When you finish receiving all markets from the GET /api/v1/markets endpoint, compare the sequence id of the markets snapshot to the sequence ids of each cached websocket message.
5. If update.seq > snapshot.seq, then apply the update to your local store of markets.

Subsequent `update` messages pertain to changes that occur to markets, such as a new listing or resolution.

Note: the `stats` field present in the GET /api/v1/markets endpoint does not exist in the websocket update message. If needed, you can get stats from the GET /api/v1/markets endpoint.

**Channel Descriptor**

| Field | Type | Description |
|---|---|---|
| `channel` | string literal `"market_update"` | Channel discriminator. |


**Update Type**

#### MarketUpdateType

Reason a market appeared on the `market_update` channel.

| Value |
|---|
| `"new"` |
| `"display_attributes_change"` |
| `"resolved"` |


**JSON Message Payload**

| Field | Type | Description |
|---|---|---|
| `update_type` | [MarketUpdateType](#marketupdatetype) | Update type. |
| `market` | [MarketStateMsg](#marketstatemsg) | Market. |


```json
{
  "channel": "market_update",
  "type": "snapshot",
  "data": [],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

```json
{
  "channel": "market_update",
  "type": "update",
  "data": [
    {
      "update_type": "new",
      "market": {
        "symbol": "SIM_EVENT_1.MARKET_1",
        "taker_fee_rate": "0.001000",
        "maker_rebate_share": "0.500000",
        "tick_size_min": "0.010000",
        "tick_sig_figs": 2,
        "display_attributes": {
          "event_description": "API documentation sample market",
          "expected_resolution_time_ms": "1735000000000",
          "market_description": "Yes",
          "reverse_description": "No",
          "sort_order": "SYMBOL_ASC",
          "tags": [
            "Docs"
          ],
          "topic": {
            "id": "docs",
            "description": "Documentation examples"
          }
        },
        "listing_ts_ms": "1731536000000",
        "rules_url": "https://sample-rules-url.com/events/SIM_EVENT_1/SIM_EVENT_1.MARKET_1.md",
        "mark_price": "0.550000",
        "open_interest": "250"
      }
    }
  ],
  "seq": "67891",
  "state_time_ms": "1731536000050",
  "server_time_ms": "1731536000123"
}
```

## Reference Types

### Error Codes

API errors return an error envelope whose `data` object has these fields:

| Field | Type | Description |
|---|---|---|
| `code` | [ApiErrorCode](#apierrorcode) | Stable, machine-readable error code. |
| `message` | string | Human-readable error message. May evolve over time. For debugging and display only. |


Error codes are `SCREAMING_SNAKE_CASE` identifiers. Use `code` for client
control flow and `message` for display, logging, and more specific diagnostics.

Stable error codes:

#### ApiErrorCode

Stable machine-readable error codes for public API operations.

| Value | Description |
|---|---|
| `"INVALID_JSON"` | The request body could not be parsed as valid JSON. |
| `"INVALID_REQUEST"` | The request was well-formed JSON but failed validation, such as a missing or malformed field, or a value outside its accepted range. |
| `"UNAUTHORIZED"` | The request signature was missing or invalid, or the signing key is not authorized to act for the account. |
| `"SYMBOL_NOT_FOUND"` | A request referenced a symbol that does not exist. |
| `"ACCOUNT_NOT_FOUND"` | A request referenced an account owner that does not exist. |
| `"ACCOUNT_RESTRICTED"` | The account is restricted by compliance policy. |
| `"GEO_RESTRICTED"` | The request is restricted by geography policy. |
| `"INVALID_GEO_HEADERS"` | Required Cloudflare geo headers were missing, malformed, or unusable. |
| `"ORDER_NOT_FOUND"` | The referenced order does not exist or is no longer open. |
| `"TRADING_KEY_NOT_FOUND"` | The referenced trading key does not exist for the account. |
| `"DUPLICATE_REQUEST"` | A request with the same signature was already received. |
| `"DUPLICATE_CLIENT_ORDER_ID"` | An open order with the same `client_order_id` already exists for the account. |
| `"UNSUPPORTED_ORDER_TYPE"` | The requested order type is not supported. |
| `"INVALID_SIZE"` | The order size is zero or otherwise invalid for the market. |
| `"INVALID_PRICE"` | The order price is out of range or not a multiple of the market's tick size. |
| `"INVALID_EXPIRATION"` | The provided expiration timestamp is invalid for the order's time in force. |
| `"WOULD_CROSS"` | A post-only order was rejected because it would have crossed the book and traded as a taker. |
| `"SELF_TRADE"` | The order was rejected because it would have matched against another of the account's own resting orders. |
| `"INSUFFICIENT_COLLATERAL"` | The account does not have enough free collateral to place the order. |
| `"NOT_FUNDED"` | The account has not been funded and cannot trade. |
| `"DEPOSIT_ADDRESS_NOT_REGISTERED"` | The account has not registered a Pascal deposit address. |
| `"MARKET_RESOLVED"` | The market has resolved and no longer accepts orders. |
| `"POSITION_LIMIT_EXCEEDED"` | The order would move the account's position beyond the market's position limit. |
| `"TRADING_KEY_SLOTS_FULL"` | The account has reached its maximum number of trading keys. |
| `"TRADING_KEY_PUB_KEY_ALREADY_USED"` | A trading key with the same public key already exists for the account. |
| `"TRADING_KEY_NAME_ALREADY_USED"` | A trading key with the same name already exists for the account. |
| `"TRADING_KEY_MUST_OVERWRITE_WITH_GREATER_EXPIRATION"` | Overwriting an existing trading key requires an expiration later than the current one. |
| `"REDUCE_ONLY_REJECTED"` | A reduce-only order was rejected because it would have increased the account's position. |
| `"PENDING_WALLET_OP_CONFLICTS"` | Another wallet-signed operation (such as a withdrawal) is already in flight for the account; retry once it settles. |
| `"PENDING_DEPOSIT_REGISTRATION"` | Deposit-address registration is already being processed for this account. |
| `"REPLACEMENT_ORDER_NOT_FOUND"` | The order targeted for replacement does not exist or is no longer open. |
| `"REPLACEMENT_ORDER_DIFF_MARKET"` | The replacement order's market differs from the order being replaced. |
| `"REPLACEMENT_ORDER_DIFF_SIDE"` | The replacement order's side differs from the order being replaced. |
| `"RECV_WINDOW_TOO_LARGE"` | The request's `recv_window_ms` exceeds the maximum allowed value. |
| `"CLIENT_TS_TOO_FAR_IN_FUTURE"` | The request's `client_ts_ms` is too far ahead of server time, beyond the allowed clock-skew tolerance. |
| `"CLIENT_TS_EXPIRED"` | The request expired: `server_time_ms - client_ts_ms` exceeded `recv_window_ms`. |
| `"CLIENT_TS_NOT_INCREASING"` | A wallet-signed request's `client_ts_ms` did not increase past the last accepted timestamp nonce for the account. |
| `"CONFLICT"` | The request conflicts with existing state, such as creating something that already exists. |
| `"RATE_LIMITED"` | The client exceeded its rate limit; slow down before retrying. |
| `"BACKPRESSURE"` | The server is shedding load and rejected the request; retry after a short delay. |
| `"NOT_READY"` | The service is still starting up or catching up and cannot serve the request yet. |
| `"HISTORY_NOT_READY"` | Historical data has not reached the requested pagination boundary. Retry the same boundary after a delay. |
| `"BAD_GATEWAY"` | Transient upstream failure, retry. |
| `"SERVICE_UNAVAILABLE"` | The service is temporarily unavailable; retry later. |
| `"WRITE_RESULT_UNAVAILABLE"` | The write request reached the write pipeline, but the service could not return a result. |
| `"TIMEOUT"` | The request timed out before completing. |
| `"INTERNAL_ERROR"` | An unexpected internal error occurred. |
| `"REFERRAL_CODE_INVALID"` | The provided Referral Code could not be resolved for registration. |
| `"BUILDER_FEE_RATE_INVALID"` | The order's builder fee rate is outside the accepted range. |
| `"BUILDER_INVALID"` | The order's builder pubkey is not accepted as a builder. |
| `"BUILDER_COLLATERAL_BELOW_MINIMUM"` | The order's builder is below the minimum free collateral required to be named on new orders. |