@compass-labs/api-sdk 2.2.92 → 2.2.93

package/docs/models/components/perpetualtradingactivityresponse.md

@@ -0,0 +1,46 @@
+# PerpetualTradingActivityResponse
+
+Aggregated HL activity for a single end-user.
+
+Any section may be ``null`` if its upstream HL call failed — see
+``partial_errors`` for details. ``positions``/``fills``/``open_orders``
+are always either a populated list or ``null``; an empty list means the
+user has no activity of that type, not a failure.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingActivityResponse } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingActivityResponse = {
+  owner: "<value>",
+  positions: [],
+  accountValue: "<value>",
+  withdrawable: "<value>",
+  fills: [
+    {
+      asset: "<value>",
+      side: "sell",
+      price: "639.99",
+      size: "<value>",
+      fee: "<value>",
+      orderId: 156289,
+      timeMs: 277362,
+    },
+  ],
+  openOrders: [],
+};
+```
+
+## Fields
+
+| Field                                                                                                                | Type                                                                                                                 | Required                                                                                                             | Description                                                                                                          |
+| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `owner`                                                                                                              | *string*                                                                                                             | :heavy_check_mark:                                                                                                   | Owner address that was queried (checksummed)                                                                         |
+| `positions`                                                                                                          | [components.PerpetualTradingPosition](../../models/components/perpetualtradingposition.md)[]                         | :heavy_check_mark:                                                                                                   | Open positions (null if the upstream call failed)                                                                    |
+| `accountValue`                                                                                                       | *string*                                                                                                             | :heavy_check_mark:                                                                                                   | Total account value in USDC (null if positions failed)                                                               |
+| `withdrawable`                                                                                                       | *string*                                                                                                             | :heavy_check_mark:                                                                                                   | Withdrawable USDC balance (null if positions failed)                                                                 |
+| `fills`                                                                                                              | [components.PerpetualTradingFill](../../models/components/perpetualtradingfill.md)[]                                 | :heavy_check_mark:                                                                                                   | Recent fills (null if the upstream call failed)                                                                      |
+| `openOrders`                                                                                                         | [components.PerpetualTradingOpenOrder](../../models/components/perpetualtradingopenorder.md)[]                       | :heavy_check_mark:                                                                                                   | Resting orders (null if the upstream call failed)                                                                    |
+| `builderApproval`                                                                                                    | [components.PerpetualTradingBuilderApproval](../../models/components/perpetualtradingbuilderapproval.md)             | :heavy_minus_sign:                                                                                                   | Builder approval state — only present when the `builder` query parameter was supplied (null on upstream failure).    |
+| `partialErrors`                                                                                                      | [components.PerpetualTradingActivityPartialError](../../models/components/perpetualtradingactivitypartialerror.md)[] | :heavy_minus_sign:                                                                                                   | One entry per section that failed to load.                                                                           |

package/docs/models/components/perpetualtradingapprovebuilderfeerequest.md

@@ -0,0 +1,24 @@
+# PerpetualTradingApproveBuilderFeeRequest
+
+Request to approve builder fees before trading on the perpetual trading DEX.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingApproveBuilderFeeRequest } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingApproveBuilderFeeRequest = {
+  owner: "0x06A9aF046187895AcFc7258450B15397CAc67400",
+  builder: {
+    address: "0x88806A71D74AD0a510B350545C9AE490912F0888",
+    maxFeeRate: "0.01%",
+  },
+};
+```
+
+## Fields
+
+| Field                                                    | Type                                                     | Required                                                 | Description                                              | Example                                                  |
+| -------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- |
+| `owner`                                                  | *string*                                                 | :heavy_check_mark:                                       | User's EOA address                                       | 0x06A9aF046187895AcFc7258450B15397CAc67400               |
+| `builder`                                                | [components.Builder](../../models/components/builder.md) | :heavy_check_mark:                                       | Builder address + max fee rate the end-user authorizes.  |                                                          |

package/docs/models/components/perpetualtradingbuilderapproval.md

@@ -0,0 +1,23 @@
+# PerpetualTradingBuilderApproval
+
+Current builder-fee approval state for a (user, builder) pair.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingBuilderApproval } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingBuilderApproval = {
+  builder: "<value>",
+  maxFeeTenthBps: 621102,
+  approved: true,
+};
+```
+
+## Fields
+
+| Field                                                                                                                                        | Type                                                                                                                                         | Required                                                                                                                                     | Description                                                                                                                                  |
+| -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `builder`                                                                                                                                    | *string*                                                                                                                                     | :heavy_check_mark:                                                                                                                           | Builder address that was queried                                                                                                             |
+| `maxFeeTenthBps`                                                                                                                             | *number*                                                                                                                                     | :heavy_check_mark:                                                                                                                           | Maximum fee rate the user has approved for this builder, in tenths of basis points (10 = 1bp = 0.01%). Zero means the user has not approved. |
+| `approved`                                                                                                                                   | *boolean*                                                                                                                                    | :heavy_check_mark:                                                                                                                           | Convenience flag — true when max_fee_tenth_bps > 0                                                                                           |

package/docs/models/components/perpetualtradingcancelorderrequest.md

@@ -0,0 +1,24 @@
+# PerpetualTradingCancelOrderRequest
+
+Request to cancel an open order on a perpetual trading market.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingCancelOrderRequest } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingCancelOrderRequest = {
+  owner: "0x06A9aF046187895AcFc7258450B15397CAc67400",
+  asset: "AAPL",
+  orderId: 12345,
+};
+```
+
+## Fields
+
+| Field                                               | Type                                                | Required                                            | Description                                         | Example                                             |
+| --------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------- |
+| `owner`                                             | *string*                                            | :heavy_check_mark:                                  | Owner of the perpetual trading product account      | 0x06A9aF046187895AcFc7258450B15397CAc67400          |
+| `asset`                                             | *string*                                            | :heavy_check_mark:                                  | Asset ticker symbol (e.g. AAPL, GOLD, EUR)          | AAPL                                                |
+| `orderId`                                           | *number*                                            | :heavy_minus_sign:                                  | Hyperliquid order ID to cancel                      | 12345                                               |
+| `clientOrderId`                                     | *number*                                            | :heavy_minus_sign:                                  | Client order ID to cancel (alternative to order_id) |                                                     |

package/docs/models/components/perpetualtradingcandlesresponse.md

@@ -0,0 +1,33 @@
+# PerpetualTradingCandlesResponse
+
+OHLCV candle series for a single asset/interval.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingCandlesResponse } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingCandlesResponse = {
+  symbol: "<value>",
+  interval: "<value>",
+  candles: [
+    {
+      time: 840003,
+      open: "<value>",
+      high: "<value>",
+      low: "<value>",
+      close: "<value>",
+      volume: "<value>",
+      trades: 811477,
+    },
+  ],
+};
+```
+
+## Fields
+
+| Field                                                    | Type                                                     | Required                                                 | Description                                              |
+| -------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- |
+| `symbol`                                                 | *string*                                                 | :heavy_check_mark:                                       | Asset ticker the candles are for (without DEX prefix)    |
+| `interval`                                               | *string*                                                 | :heavy_check_mark:                                       | Candle interval that was requested                       |
+| `candles`                                                | [components.Candle](../../models/components/candle.md)[] | :heavy_check_mark:                                       | Candles ordered oldest → newest                          |

package/docs/models/components/perpetualtradingcategory.md

@@ -0,0 +1,15 @@
+# PerpetualTradingCategory
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingCategory } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingCategory = "forex";
+```
+
+## Values
+
+```typescript
+"stock" | "commodity" | "forex"
+```

package/docs/models/components/perpetualtradingdepositrequest.md

@@ -0,0 +1,21 @@
+# PerpetualTradingDepositRequest
+
+Request to deposit USDC from Arbitrum into the user's perpetual trading account.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingDepositRequest } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingDepositRequest = {
+  owner: "0x06A9aF046187895AcFc7258450B15397CAc67400",
+  amount: "100.0",
+};
+```
+
+## Fields
+
+| Field                                                  | Type                                                   | Required                                               | Description                                            | Example                                                |
+| ------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------ |
+| `owner`                                                | *string*                                               | :heavy_check_mark:                                     | The user's EOA address on Arbitrum                     | 0x06A9aF046187895AcFc7258450B15397CAc67400             |
+| `amount`                                               | *string*                                               | :heavy_check_mark:                                     | USDC amount to deposit (human-readable, e.g. '1000.0') | 100.0                                                  |

package/docs/models/components/perpetualtradingdepositresponse.md

@@ -0,0 +1,56 @@
+# PerpetualTradingDepositResponse
+
+EIP-2612 permit data the user signs to authorize a USDC bridge deposit.
+
+After signing, submit the signature to /v2/perpetual_trading/deposit/sponsor_prepare
+to get a ready-to-broadcast Arbitrum tx that calls Bridge2.batchedDepositWithPermit.
+The integrator's sponsor wallet broadcasts that tx — Compass does not broadcast.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingDepositResponse } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingDepositResponse = {
+  permit: {
+    domain: {
+      name: "<value>",
+      version: "<value>",
+      chainId: 499115,
+      verifyingContract: "<value>",
+    },
+    types: {
+      eip712Domain: [
+        {
+          name: "<value>",
+          type: "<value>",
+        },
+      ],
+      permit: [
+        {
+          name: "<value>",
+          type: "<value>",
+        },
+      ],
+    },
+    primaryType: "Permit",
+    message: {
+      owner: "<value>",
+      spender: "<value>",
+      value: "<value>",
+      nonce: "<value>",
+      deadline: "<value>",
+    },
+  },
+  amountRaw: 979671,
+  destination: "<value>",
+};
+```
+
+## Fields
+
+| Field                                                                                                          | Type                                                                                                           | Required                                                                                                       | Description                                                                                                    |
+| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `permit`                                                                                                       | [components.PermitTypedDataResponseOutput](../../models/components/permittypeddataresponseoutput.md)           | :heavy_check_mark:                                                                                             | Response containing EIP-712 typed data for ERC-20 Permit signing.                                              |
+| `amountRaw`                                                                                                    | *number*                                                                                                       | :heavy_check_mark:                                                                                             | USDC amount in raw 6-decimal units. Pass this and the signature to /deposit/sponsor_prepare.                   |
+| `destination`                                                                                                  | *string*                                                                                                       | :heavy_check_mark:                                                                                             | Address that will be credited on Hyperliquid (equals the deposit owner EOA — HL keys accounts by EVM address). |

package/docs/models/components/perpetualtradingdepositsponsorpreparerequest.md

@@ -0,0 +1,32 @@
+# PerpetualTradingDepositSponsorPrepareRequest
+
+Take a user's signed EIP-2612 USDC permit and build an Arbitrum tx
+that calls Bridge2.batchedDepositWithPermit.
+
+The customer broadcasts the returned tx from their own sponsor wallet —
+Compass does not hold gas keys (non-custodial).
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingDepositSponsorPrepareRequest } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingDepositSponsorPrepareRequest = {
+  owner: "0x06A9aF046187895AcFc7258450B15397CAc67400",
+  amountRaw: 100000000,
+  deadline: 1747097383,
+  signature:
+    "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+  sender: "0x4A83b4413CF41C3244027e1590E35a0F48403F0c",
+};
+```
+
+## Fields
+
+| Field                                                                                                                                | Type                                                                                                                                 | Required                                                                                                                             | Description                                                                                                                          | Example                                                                                                                              |
+| ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `owner`                                                                                                                              | *string*                                                                                                                             | :heavy_check_mark:                                                                                                                   | The user's EOA address on Arbitrum (the permit signer).                                                                              | 0x06A9aF046187895AcFc7258450B15397CAc67400                                                                                           |
+| `amountRaw`                                                                                                                          | *number*                                                                                                                             | :heavy_check_mark:                                                                                                                   | USDC amount in raw 6-decimal units, as returned by /deposit.                                                                         | 100000000                                                                                                                            |
+| `deadline`                                                                                                                           | *number*                                                                                                                             | :heavy_check_mark:                                                                                                                   | Permit deadline (unix seconds), as returned in the permit.message from /deposit.                                                     | 1747097383                                                                                                                           |
+| `signature`                                                                                                                          | *string*                                                                                                                             | :heavy_check_mark:                                                                                                                   | The user's EIP-2612 permit signature (65-byte hex, 0x-prefixed or raw).                                                              | 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 |
+| `sender`                                                                                                                             | *string*                                                                                                                             | :heavy_check_mark:                                                                                                                   | Sponsor wallet address that will broadcast the returned tx (used for `from` and nonce).                                              | 0x4A83b4413CF41C3244027e1590E35a0F48403F0c                                                                                           |

package/docs/models/components/perpetualtradingdepositsponsorprepareresponse.md

@@ -0,0 +1,33 @@
+# PerpetualTradingDepositSponsorPrepareResponse
+
+Fully-encoded Arbitrum tx that completes a HL Bridge2 deposit.
+
+Broadcast `transaction` from the `sender` wallet supplied in the request.
+After the receipt confirms, verify a USDC `Transfer` event was emitted —
+Bridge2 can silently no-op without reverting.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingDepositSponsorPrepareResponse } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingDepositSponsorPrepareResponse = {
+  transaction: {
+    chainId: "<id>",
+    data: "<value>",
+    from: "<value>",
+    gas: "<value>",
+    to: "<value>",
+    value: "<value>",
+    nonce: "<value>",
+    maxFeePerGas: "<value>",
+    maxPriorityFeePerGas: "<value>",
+  },
+};
+```
+
+## Fields
+
+| Field                                                                            | Type                                                                             | Required                                                                         | Description                                                                      |
+| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `transaction`                                                                    | [components.UnsignedTransaction](../../models/components/unsignedtransaction.md) | :heavy_check_mark:                                                               | N/A                                                                              |

package/docs/models/components/perpetualtradingenableunifiedaccountrequest.md

@@ -0,0 +1,19 @@
+# PerpetualTradingEnableUnifiedAccountRequest
+
+Request to enable unified account mode on Hyperliquid.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingEnableUnifiedAccountRequest } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingEnableUnifiedAccountRequest = {
+  owner: "<value>",
+};
+```
+
+## Fields
+
+| Field              | Type               | Required           | Description        |
+| ------------------ | ------------------ | ------------------ | ------------------ |
+| `owner`            | *string*           | :heavy_check_mark: | User's EOA address |

package/docs/models/components/perpetualtradingenableunifiedaccountresponse.md

@@ -0,0 +1,25 @@
+# PerpetualTradingEnableUnifiedAccountResponse
+
+Returned by the enable_unified_account endpoint.
+
+If the account is already in unified mode, typed_data/action/nonce are null.
+If not, they contain the EIP-712 payload the user must sign.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingEnableUnifiedAccountResponse } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingEnableUnifiedAccountResponse = {
+  mode: "<value>",
+};
+```
+
+## Fields
+
+| Field                                                                 | Type                                                                  | Required                                                              | Description                                                           |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `mode`                                                                | *string*                                                              | :heavy_check_mark:                                                    | Current account abstraction mode (e.g. 'default', 'unifiedAccount')   |
+| `typedData`                                                           | Record<string, *any*>                                                 | :heavy_minus_sign:                                                    | EIP-712 typed data for wallet signing, or null if already unified     |
+| `action`                                                              | Record<string, *any*>                                                 | :heavy_minus_sign:                                                    | Raw Hyperliquid action (passed back to the execute endpoint), or null |
+| `nonce`                                                               | *number*                                                              | :heavy_minus_sign:                                                    | Timestamp-based nonce, or null if no action needed                    |

package/docs/models/components/perpetualtradingensureleveragerequest.md

@@ -0,0 +1,21 @@
+# PerpetualTradingEnsureLeverageRequest
+
+Request to check and set leverage to 1x cross on a perpetual trading asset.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingEnsureLeverageRequest } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingEnsureLeverageRequest = {
+  owner: "<value>",
+  asset: "<value>",
+};
+```
+
+## Fields
+
+| Field                            | Type                             | Required                         | Description                      |
+| -------------------------------- | -------------------------------- | -------------------------------- | -------------------------------- |
+| `owner`                          | *string*                         | :heavy_check_mark:               | User's EOA address               |
+| `asset`                          | *string*                         | :heavy_check_mark:               | Asset ticker (e.g. 'AAPL', 'CL') |

package/docs/models/components/perpetualtradingensureleverageresponse.md

@@ -0,0 +1,25 @@
+# PerpetualTradingEnsureLeverageResponse
+
+Returned by the ensure_leverage endpoint.
+
+If the asset is already at 1x cross leverage, typed_data/action/nonce are null.
+If not (or no position exists), they contain the EIP-712 payload the user must sign.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingEnsureLeverageResponse } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingEnsureLeverageResponse = {
+  leverageOk: true,
+};
+```
+
+## Fields
+
+| Field                                                                 | Type                                                                  | Required                                                              | Description                                                           |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `leverageOk`                                                          | *boolean*                                                             | :heavy_check_mark:                                                    | True if leverage is already 1x cross, false if update needed          |
+| `typedData`                                                           | Record<string, *any*>                                                 | :heavy_minus_sign:                                                    | EIP-712 typed data for wallet signing, or null if already 1x cross    |
+| `action`                                                              | Record<string, *any*>                                                 | :heavy_minus_sign:                                                    | Raw Hyperliquid action (passed back to the execute endpoint), or null |
+| `nonce`                                                               | *number*                                                              | :heavy_minus_sign:                                                    | Timestamp-based nonce, or null if no action needed                    |

package/docs/models/components/perpetualtradingexecuterequest.md

@@ -0,0 +1,24 @@
+# PerpetualTradingExecuteRequest
+
+Submit a signed Hyperliquid action for execution.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingExecuteRequest } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingExecuteRequest = {
+  action: {},
+  nonce: 291578,
+  signature: "<value>",
+};
+```
+
+## Fields
+
+| Field                                        | Type                                         | Required                                     | Description                                  |
+| -------------------------------------------- | -------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
+| `action`                                     | Record<string, *any*>                        | :heavy_check_mark:                           | Raw Hyperliquid action from the prepare step |
+| `nonce`                                      | *number*                                     | :heavy_check_mark:                           | Nonce from the prepare step                  |
+| `signature`                                  | *string*                                     | :heavy_check_mark:                           | User's EIP-712 signature (hex, 65 bytes)     |
+| `vaultAddress`                               | *string*                                     | :heavy_minus_sign:                           | Optional vault address                       |

package/docs/models/components/perpetualtradingexecuteresponse.md

@@ -0,0 +1,20 @@
+# PerpetualTradingExecuteResponse
+
+Returned after submitting a signed action to the Hyperliquid exchange.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingExecuteResponse } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingExecuteResponse = {
+  status: "<value>",
+};
+```
+
+## Fields
+
+| Field                                            | Type                                             | Required                                         | Description                                      |
+| ------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------ |
+| `status`                                         | *string*                                         | :heavy_check_mark:                               | 'ok' or 'error'                                  |
+| `response`                                       | Record<string, *any*>                            | :heavy_minus_sign:                               | Hyperliquid response data (order statuses, etc.) |

package/docs/models/components/perpetualtradingfill.md

@@ -0,0 +1,33 @@
+# PerpetualTradingFill
+
+A single fill (executed trade) from HL `userFills`.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingFill } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingFill = {
+  asset: "<value>",
+  side: "buy",
+  price: "292.09",
+  size: "<value>",
+  fee: "<value>",
+  orderId: 679407,
+  timeMs: 496876,
+};
+```
+
+## Fields
+
+| Field                                                                                      | Type                                                                                       | Required                                                                                   | Description                                                                                |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `asset`                                                                                    | *string*                                                                                   | :heavy_check_mark:                                                                         | Asset ticker symbol (xyz prefix stripped)                                                  |
+| `side`                                                                                     | [components.PerpetualTradingFillSide](../../models/components/perpetualtradingfillside.md) | :heavy_check_mark:                                                                         | Order side                                                                                 |
+| `price`                                                                                    | *string*                                                                                   | :heavy_check_mark:                                                                         | Fill price                                                                                 |
+| `size`                                                                                     | *string*                                                                                   | :heavy_check_mark:                                                                         | Fill size in contracts                                                                     |
+| `fee`                                                                                      | *string*                                                                                   | :heavy_check_mark:                                                                         | Total fee paid (USDC)                                                                      |
+| `builderFee`                                                                               | *string*                                                                                   | :heavy_minus_sign:                                                                         | Portion of fee routed to the builder address (USDC)                                        |
+| `closedPnl`                                                                                | *string*                                                                                   | :heavy_minus_sign:                                                                         | Realized PnL closed by this fill (USDC)                                                    |
+| `orderId`                                                                                  | *number*                                                                                   | :heavy_check_mark:                                                                         | HL order id (oid) this fill belongs to                                                     |
+| `timeMs`                                                                                   | *number*                                                                                   | :heavy_check_mark:                                                                         | Fill timestamp (ms since epoch)                                                            |

package/docs/models/components/perpetualtradingfillside.md

@@ -0,0 +1,17 @@
+# PerpetualTradingFillSide
+
+Order side
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingFillSide } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingFillSide = "buy";
+```
+
+## Values
+
+```typescript
+"buy" | "sell"
+```

package/docs/models/components/perpetualtradinglimitorderrequest.md

@@ -0,0 +1,33 @@
+# PerpetualTradingLimitOrderRequest
+
+Request to place a limit order on a perpetual trading market.
+
+## Example Usage
+
+```typescript
+import { PerpetualTradingLimitOrderRequest } from "@compass-labs/api-sdk/models/components";
+
+let value: PerpetualTradingLimitOrderRequest = {
+  owner: "0x06A9aF046187895AcFc7258450B15397CAc67400",
+  asset: "AAPL",
+  side: "buy",
+  size: "10.0",
+  price: "190.00",
+  timeInForce: "gtc",
+  reduceOnly: false,
+};
+```
+
+## Fields
+
+| Field                                                                                                                                                                                                                                                           | Type                                                                                                                                                                                                                                                            | Required                                                                                                                                                                                                                                                        | Description                                                                                                                                                                                                                                                     | Example                                                                                                                                                                                                                                                         |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `owner`                                                                                                                                                                                                                                                         | *string*                                                                                                                                                                                                                                                        | :heavy_check_mark:                                                                                                                                                                                                                                              | Owner of the perpetual trading product account                                                                                                                                                                                                                  | 0x06A9aF046187895AcFc7258450B15397CAc67400                                                                                                                                                                                                                      |
+| `asset`                                                                                                                                                                                                                                                         | *string*                                                                                                                                                                                                                                                        | :heavy_check_mark:                                                                                                                                                                                                                                              | Asset ticker symbol (e.g. AAPL, GOLD, EUR)                                                                                                                                                                                                                      | AAPL                                                                                                                                                                                                                                                            |
+| `side`                                                                                                                                                                                                                                                          | *string*                                                                                                                                                                                                                                                        | :heavy_check_mark:                                                                                                                                                                                                                                              | Order side: 'buy' or 'sell'                                                                                                                                                                                                                                     | buy                                                                                                                                                                                                                                                             |
+| `size`                                                                                                                                                                                                                                                          | *string*                                                                                                                                                                                                                                                        | :heavy_check_mark:                                                                                                                                                                                                                                              | Number of contracts (human-readable)                                                                                                                                                                                                                            | 10.0                                                                                                                                                                                                                                                            |
+| `price`                                                                                                                                                                                                                                                         | *string*                                                                                                                                                                                                                                                        | :heavy_check_mark:                                                                                                                                                                                                                                              | Limit price (human-readable)                                                                                                                                                                                                                                    | 190.00                                                                                                                                                                                                                                                          |
+| `timeInForce`                                                                                                                                                                                                                                                   | *string*                                                                                                                                                                                                                                                        | :heavy_minus_sign:                                                                                                                                                                                                                                              | Time-in-force: 'gtc' (good til cancel) or 'alo' (add liquidity only)                                                                                                                                                                                            | gtc                                                                                                                                                                                                                                                             |
+| `reduceOnly`                                                                                                                                                                                                                                                    | *boolean*                                                                                                                                                                                                                                                       | :heavy_minus_sign:                                                                                                                                                                                                                                              | If true, order can only reduce an existing position                                                                                                                                                                                                             | false                                                                                                                                                                                                                                                           |
+| `clientOrderId`                                                                                                                                                                                                                                                 | *number*                                                                                                                                                                                                                                                        | :heavy_minus_sign:                                                                                                                                                                                                                                              | Optional client order ID for idempotency (uint128)                                                                                                                                                                                                              |                                                                                                                                                                                                                                                                 |
+| `builder`                                                                                                                                                                                                                                                       | [components.Builder](../../models/components/builder.md)                                                                                                                                                                                                        | :heavy_minus_sign:                                                                                                                                                                                                                                              | Optional builder fee. When provided, the order action carries the builder address and fee — the end-user must have already approved this builder via /approve_builder_fee up to at least this rate. Omit (or pass null) to place the order with no builder fee. |                                                                                                                                                                                                                                                                 |