docs: sync Polymarket docs updates 2026-07-13 - add 90 new pages incl. Perps section

docs/api-reference/apply-referral-code.md

@@ -0,0 +1,226 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Apply Referral Code
+
+> Apply a referral code to the authenticated account after signup. Accounts
+can only apply a referral code if they do not already have one.
+
+
+<Badge color="gray" size="md">Request Weight: **1**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json post /v1/account/referral
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/referral:
+    post:
+      summary: Apply Referral Code
+      description: >
+        Apply a referral code to the authenticated account after signup.
+        Accounts
+
+        can only apply a referral code if they do not already have one.
+      operationId: applyReferral
+      requestBody:
+        required: true
+        description: Referral code to apply.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AccountReferralRequest'
+            examples:
+              applyReferral:
+                summary: Apply a referral code
+                value:
+                  code: ABC123
+      responses:
+        '200':
+          description: Referral code accepted.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GenericAccepted'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    AccountReferralRequest:
+      type: object
+      required:
+        - code
+      properties:
+        code:
+          $ref: '#/components/schemas/code'
+    GenericAccepted:
+      type: object
+      required:
+        - status
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+    code:
+      type: string
+      description: Referral or invite code
+      example: ABC123
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/cancel-orders-coid.md

@@ -0,0 +1,278 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Cancel Orders COID
+
+> Cancel orders by client order ID.
+Requires proxy signature, see [proxy signing](/http/signing#2-proxy-signing).
+
+
+<Badge color="gray" size="md">Request Weight: **1 + floor(n / 20)**</Badge> <Badge color="gray" size="md">Action Weight: **0**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json delete /v1/trade/orders-coid
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/trade/orders-coid:
+    delete:
+      summary: Cancel Orders COID
+      description: >
+        Cancel orders by client order ID.
+
+        Requires proxy signature, see [proxy
+        signing](/http/signing#2-proxy-signing).
+      operationId: cancelOrdersByCoid
+      requestBody:
+        description: Cancel by coid request.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CancelByCoidRequest'
+      responses:
+        '200':
+          description: Cancel response.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/CancelResponse'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    CancelByCoidRequest:
+      allOf:
+        - type: object
+          required:
+            - op
+          properties:
+            op:
+              $ref: '#/components/schemas/OpCancelOrdersByCoid'
+        - $ref: '#/components/schemas/BaseOp'
+        - type: object
+          properties:
+            exp:
+              $ref: '#/components/schemas/exp'
+    CancelResponse:
+      oneOf:
+        - $ref: '#/components/schemas/CancelAccepted'
+        - $ref: '#/components/schemas/CancelRejected'
+    OpCancelOrdersByCoid:
+      type: object
+      required:
+        - type
+        - args
+      properties:
+        type:
+          type: string
+          enum:
+            - cancelOrdersCOID
+        args:
+          type: array
+          description: |
+            Array of client order IDs to cancel. Cancelling an order that has
+            attached take-profit / stop-loss children (see `CreateOrder.tr`)
+            cascades to those children — they are cancelled with reason
+            `ParentCancelled`.
+          items:
+            $ref: '#/components/schemas/coid'
+    BaseOp:
+      type: object
+      required:
+        - sig
+        - salt
+        - ts
+      properties:
+        sig:
+          $ref: '#/components/schemas/sig'
+        salt:
+          $ref: '#/components/schemas/salt'
+        ts:
+          $ref: '#/components/schemas/ts'
+    exp:
+      type: integer
+      description: >-
+        Command expiry timestamp in Unix milliseconds. If provided, it must be
+        in the future and within the gateway's default command timeout. It can
+        shorten request validity but cannot extend it. This is not an order
+        auto-cancel time.
+      example: 1767225600000
+    CancelAccepted:
+      type: object
+      required:
+        - status
+        - oid
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+        oid:
+          $ref: '#/components/schemas/oid'
+        coid:
+          $ref: '#/components/schemas/coid'
+          description: Echoed only when the request carried a client_order_id.
+    CancelRejected:
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        oid:
+          $ref: '#/components/schemas/oid'
+        coid:
+          $ref: '#/components/schemas/coid'
+        error:
+          $ref: '#/components/schemas/error'
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    coid:
+      type: string
+      description: Client order ID
+      minLength: 32
+      maxLength: 32
+      pattern: ^[0-9a-f]{32}$
+      example: 550e8400e29b41d4a716446655440000
+    sig:
+      type: string
+      description: Signature in hex format
+      example: 0x1234567890...
+    salt:
+      type: integer
+      description: Salt
+      example: 1234567890
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+    oid:
+      type: integer
+      description: Order ID
+      example: 1234567890
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/cancel-orders.md

@@ -0,0 +1,277 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Cancel Orders
+
+> Cancel orders.
+Requires proxy signature, see [proxy signing](/http/signing#2-proxy-signing).
+
+
+<Badge color="gray" size="md">Request Weight: **1 + floor(n / 20)**</Badge> <Badge color="gray" size="md">Action Weight: **0**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json delete /v1/trade/orders
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/trade/orders:
+    delete:
+      summary: Cancel Orders
+      description: >
+        Cancel orders.
+
+        Requires proxy signature, see [proxy
+        signing](/http/signing#2-proxy-signing).
+      operationId: cancelOrders
+      requestBody:
+        description: Cancel request.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CancelRequest'
+      responses:
+        '200':
+          description: Cancel response.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/CancelResponse'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    CancelRequest:
+      allOf:
+        - type: object
+          required:
+            - op
+          properties:
+            op:
+              $ref: '#/components/schemas/OpCancelOrders'
+        - $ref: '#/components/schemas/BaseOp'
+        - type: object
+          properties:
+            exp:
+              $ref: '#/components/schemas/exp'
+    CancelResponse:
+      oneOf:
+        - $ref: '#/components/schemas/CancelAccepted'
+        - $ref: '#/components/schemas/CancelRejected'
+    OpCancelOrders:
+      type: object
+      required:
+        - type
+        - args
+      properties:
+        type:
+          type: string
+          enum:
+            - cancelOrders
+        args:
+          type: array
+          description: |
+            Array of order IDs to cancel. Cancelling an order that has attached
+            take-profit / stop-loss children (see `CreateOrder.tr`) cascades to
+            those children — they are cancelled with reason `ParentCancelled`.
+          items:
+            $ref: '#/components/schemas/oid'
+    BaseOp:
+      type: object
+      required:
+        - sig
+        - salt
+        - ts
+      properties:
+        sig:
+          $ref: '#/components/schemas/sig'
+        salt:
+          $ref: '#/components/schemas/salt'
+        ts:
+          $ref: '#/components/schemas/ts'
+    exp:
+      type: integer
+      description: >-
+        Command expiry timestamp in Unix milliseconds. If provided, it must be
+        in the future and within the gateway's default command timeout. It can
+        shorten request validity but cannot extend it. This is not an order
+        auto-cancel time.
+      example: 1767225600000
+    CancelAccepted:
+      type: object
+      required:
+        - status
+        - oid
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+        oid:
+          $ref: '#/components/schemas/oid'
+        coid:
+          $ref: '#/components/schemas/coid'
+          description: Echoed only when the request carried a client_order_id.
+    CancelRejected:
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        oid:
+          $ref: '#/components/schemas/oid'
+        coid:
+          $ref: '#/components/schemas/coid'
+        error:
+          $ref: '#/components/schemas/error'
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    oid:
+      type: integer
+      description: Order ID
+      example: 1234567890
+    sig:
+      type: string
+      description: Signature in hex format
+      example: 0x1234567890...
+    salt:
+      type: integer
+      description: Salt
+      example: 1234567890
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+    coid:
+      type: string
+      description: Client order ID
+      minLength: 32
+      maxLength: 32
+      pattern: ^[0-9a-f]{32}$
+      example: 550e8400e29b41d4a716446655440000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/check-invite-code.md

@@ -0,0 +1,162 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Check Invite Code
+
+> Check whether an invite code can be used. When `address` is provided, the
+response is invalid if that address already has an account.
+
+
+<Badge color="gray" size="md">Request Weight: **1**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/invite
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/invite:
+    get:
+      summary: Check Invite Code
+      description: >
+        Check whether an invite code can be used. When `address` is provided,
+        the
+
+        response is invalid if that address already has an account.
+      operationId: checkInviteCode
+      parameters:
+        - name: code
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/code'
+        - name: address
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/address'
+      responses:
+        '200':
+          description: Invite code validation response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InviteCheckResponse'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    code:
+      type: string
+      description: Referral or invite code
+      example: ABC123
+    address:
+      type: string
+      description: Address
+      example: '0x1234567890abcdef1234567890abcdef12345678'
+    InviteCheckResponse:
+      type: object
+      required:
+        - valid
+      properties:
+        valid:
+          type: boolean
+          description: Whether the invite code can be used.
+        error:
+          type: string
+          description: Present when the invite code is invalid or unusable.
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/create-account-invite.md

@@ -0,0 +1,236 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Create Account Invite
+
+> Create or return the authenticated account's primary invite code. The call
+is idempotent for accounts that already have a primary invite code.
+
+
+<Badge color="gray" size="md">Request Weight: **1**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json post /v1/account/invite
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/invite:
+    post:
+      summary: Create Account Invite
+      description: >
+        Create or return the authenticated account's primary invite code. The
+        call
+
+        is idempotent for accounts that already have a primary invite code.
+      operationId: createAccountInvite
+      requestBody:
+        description: Empty invite creation request.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateInviteRequest'
+            examples:
+              createAccountInvite:
+                summary: Create or get the authenticated account invite code
+                value: {}
+      responses:
+        '200':
+          description: Account invite response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CreateInviteResponse'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    CreateInviteRequest:
+      type: object
+      additionalProperties: false
+    CreateInviteResponse:
+      type: object
+      required:
+        - status
+        - code
+        - referrals_available
+        - cooldown_ms
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+        code:
+          $ref: '#/components/schemas/code'
+        referrals_available:
+          type: integer
+          minimum: 0
+          description: Remaining lifetime referrals for this invite code.
+        cooldown_ms:
+          type: integer
+          nullable: true
+          minimum: 0
+          description: >-
+            Milliseconds until referrals become available again. Null for
+            lifetime caps because no windowed cooldown applies.
+    code:
+      type: string
+      description: Referral or invite code
+      example: ABC123
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/create-orders.md

@@ -0,0 +1,362 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Create Orders
+
+> Create new orders.
+Requires proxy signature, see [proxy signing](/http/signing#2-proxy-signing).
+
+
+<Badge color="gray" size="md">Request Weight: **1 + floor(n / 20)**</Badge> <Badge color="gray" size="md">Action Weight: **1 / order**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json post /v1/trade/orders
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/trade/orders:
+    post:
+      summary: Create Orders
+      description: >
+        Create new orders.
+
+        Requires proxy signature, see [proxy
+        signing](/http/signing#2-proxy-signing).
+      operationId: createOrders
+      requestBody:
+        description: Order request.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OrderRequest'
+      responses:
+        '200':
+          description: >-
+            Order ACK response. Order result should be fetched using the get
+            orders endpoint.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/OrderResponse'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    OrderRequest:
+      allOf:
+        - type: object
+          required:
+            - op
+          properties:
+            op:
+              $ref: '#/components/schemas/OpCreateOrders'
+        - $ref: '#/components/schemas/BaseOp'
+        - type: object
+          properties:
+            exp:
+              $ref: '#/components/schemas/exp'
+    OrderResponse:
+      oneOf:
+        - $ref: '#/components/schemas/OrderAccepted'
+        - $ref: '#/components/schemas/OrderRejected'
+    OpCreateOrders:
+      type: object
+      required:
+        - type
+        - args
+      properties:
+        type:
+          type: string
+          enum:
+            - createOrders
+        args:
+          type: array
+          items:
+            $ref: '#/components/schemas/CreateOrder'
+        grp:
+          $ref: '#/components/schemas/grp'
+    BaseOp:
+      type: object
+      required:
+        - sig
+        - salt
+        - ts
+      properties:
+        sig:
+          $ref: '#/components/schemas/sig'
+        salt:
+          $ref: '#/components/schemas/salt'
+        ts:
+          $ref: '#/components/schemas/ts'
+    exp:
+      type: integer
+      description: >-
+        Command expiry timestamp in Unix milliseconds. If provided, it must be
+        in the future and within the gateway's default command timeout. It can
+        shorten request validity but cannot extend it. This is not an order
+        auto-cancel time.
+      example: 1767225600000
+    OrderAccepted:
+      type: object
+      required:
+        - status
+        - oid
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+        oid:
+          $ref: '#/components/schemas/oid'
+        coid:
+          $ref: '#/components/schemas/coid'
+          description: Echoed only when the request carried a client_order_id.
+    OrderRejected:
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        oid:
+          $ref: '#/components/schemas/oid'
+        coid:
+          $ref: '#/components/schemas/coid'
+        error:
+          $ref: '#/components/schemas/error'
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    CreateOrder:
+      type: object
+      required:
+        - iid
+        - buy
+        - qty
+      properties:
+        iid:
+          $ref: '#/components/schemas/iid'
+        buy:
+          $ref: '#/components/schemas/buy'
+        p:
+          $ref: '#/components/schemas/p'
+        qty:
+          $ref: '#/components/schemas/qty'
+        tif:
+          $ref: '#/components/schemas/tif'
+        po:
+          $ref: '#/components/schemas/po'
+        ro:
+          $ref: '#/components/schemas/ro'
+        c:
+          $ref: '#/components/schemas/coid'
+        tr:
+          type: object
+          description: Optional trigger attached to this order.
+          properties:
+            market:
+              $ref: '#/components/schemas/market'
+            trp:
+              $ref: '#/components/schemas/trp'
+            tpsl:
+              $ref: '#/components/schemas/tpsl'
+    grp:
+      type: string
+      description: TPSL grouping
+      enum:
+        - order
+        - position
+    sig:
+      type: string
+      description: Signature in hex format
+      example: 0x1234567890...
+    salt:
+      type: integer
+      description: Salt
+      example: 1234567890
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+    oid:
+      type: integer
+      description: Order ID
+      example: 1234567890
+    coid:
+      type: string
+      description: Client order ID
+      minLength: 32
+      maxLength: 32
+      pattern: ^[0-9a-f]{32}$
+      example: 550e8400e29b41d4a716446655440000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+    iid:
+      type: integer
+      description: Instrument ID
+      example: 1
+    buy:
+      type: boolean
+      description: Is buy
+      example: true
+    p:
+      type: string
+      description: Price
+      example: '100.00'
+    qty:
+      type: string
+      description: Quantity in no. of contracts
+      example: '10.00'
+    tif:
+      type: string
+      description: Time in force
+      enum:
+        - gtc
+        - ioc
+        - fok
+    po:
+      type: boolean
+      description: Post only
+      default: false
+      example: false
+    ro:
+      type: boolean
+      description: Reduce only
+      example: false
+      default: false
+    market:
+      type: boolean
+      description: Whether the trigger executes as a market order
+    trp:
+      type: string
+      description: Trigger price
+      example: '110.00'
+    tpsl:
+      type: string
+      description: Trigger type
+      enum:
+        - tp
+        - sl
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/create-proxy.md

@@ -0,0 +1,302 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Create Proxy
+
+> Create a new proxy to sign orders. Returns an API secret for private account access.
+Requires EOA signature, see [EOA signing](/http/signing#1-eoa-signing).
+
+
+<Badge color="gray" size="md">Request Weight: **1**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json post /v1/account/proxy
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/proxy:
+    post:
+      summary: Create Proxy
+      description: >
+        Create a new proxy to sign orders. Returns an API secret for private
+        account access.
+
+        Requires EOA signature, see [EOA signing](/http/signing#1-eoa-signing).
+      operationId: createProxy
+      requestBody:
+        description: Proxy creation request.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ProxyRequest'
+            examples:
+              createProxy:
+                summary: Create a proxy
+                value:
+                  op:
+                    type: createProxy
+                    args:
+                      owner: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
+                      proxy: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'
+                      expiry: 1767225600000
+                  sig: >-
+                    0x4d11d89f6d8e2f0fd22fb5dd9e6e88a35f3a2c0f3a9e4ff9f8f0da5e6c5f241d2ed7d173f7fcb15726b8a7e7f1f1277ec54c060f5b3ab4d72dbf4d0e40ee6e9a1c
+                  salt: 123456789
+                  ts: 1767000000000
+      responses:
+        '200':
+          description: Proxy creation response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProxyResponse'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '422':
+          $ref: '#/components/responses/Error422Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    ProxyRequest:
+      allOf:
+        - type: object
+          required:
+            - op
+          properties:
+            op:
+              $ref: '#/components/schemas/OpCreateProxy'
+        - $ref: '#/components/schemas/BaseOp'
+        - type: object
+          properties:
+            label:
+              $ref: '#/components/schemas/label'
+            code:
+              $ref: '#/components/schemas/code'
+    ProxyResponse:
+      type: object
+      required:
+        - status
+        - secret
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+        secret:
+          $ref: '#/components/schemas/secret'
+    OpCreateProxy:
+      type: object
+      required:
+        - type
+        - args
+      properties:
+        type:
+          type: string
+          enum:
+            - createProxy
+        args:
+          type: object
+          required:
+            - owner
+            - proxy
+            - expiry
+          properties:
+            owner:
+              $ref: '#/components/schemas/owner'
+            proxy:
+              $ref: '#/components/schemas/proxy'
+            expiry:
+              $ref: '#/components/schemas/expiry'
+    BaseOp:
+      type: object
+      required:
+        - sig
+        - salt
+        - ts
+      properties:
+        sig:
+          $ref: '#/components/schemas/sig'
+        salt:
+          $ref: '#/components/schemas/salt'
+        ts:
+          $ref: '#/components/schemas/ts'
+    label:
+      type: string
+      description: Human-readable label for a proxy key or internal transfer
+      example: trading-bot
+    code:
+      type: string
+      description: Referral or invite code
+      example: ABC123
+    secret:
+      type: string
+      description: API secret
+      example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    GenericRejected:
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    owner:
+      type: string
+      description: Owner address in hex format
+      example: '0x1234567890abcdef1234567890abcdef12345678'
+    proxy:
+      type: string
+      description: Proxy address in hex format
+      example: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'
+    expiry:
+      type: integer
+      description: Expiry timestamp in milliseconds
+      example: 1767225600000
+    sig:
+      type: string
+      description: Signature in hex format
+      example: 0x1234567890...
+    salt:
+      type: integer
+      description: Salt
+      example: 1234567890
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error422Response:
+      description: |
+        Unprocessable Entity — the request was well-formed but a domain rule
+        rejected it on its merits (insufficient balance, invalid leverage,
+        proxy already exists, …). The body is the discriminated rejection
+        (`status: err`) with the engine error identifier in `error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/GenericRejected'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/delete-proxy.md

@@ -0,0 +1,263 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Delete Proxy
+
+> Delete a proxy by address.
+Requires EOA signature, see [EOA signing](/http/signing#1-eoa-signing).
+
+
+<Badge color="gray" size="md">Request Weight: **1**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json delete /v1/account/proxy
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/proxy:
+    delete:
+      summary: Delete Proxy
+      description: |
+        Delete a proxy by address.
+        Requires EOA signature, see [EOA signing](/http/signing#1-eoa-signing).
+      operationId: deleteProxy
+      requestBody:
+        description: Delete proxy request.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DeleteProxyRequest'
+            examples:
+              deleteProxy:
+                summary: Delete a proxy
+                value:
+                  op:
+                    type: deleteProxy
+                    args:
+                      proxy: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'
+                  sig: >-
+                    0x9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a1c
+                  salt: 888888888
+                  ts: 1767000020000
+      responses:
+        '200':
+          description: Delete proxy response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GenericAccepted'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '422':
+          $ref: '#/components/responses/Error422Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    DeleteProxyRequest:
+      allOf:
+        - type: object
+          required:
+            - op
+          properties:
+            op:
+              $ref: '#/components/schemas/OpDeleteProxy'
+        - $ref: '#/components/schemas/BaseOp'
+    GenericAccepted:
+      type: object
+      required:
+        - status
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+    OpDeleteProxy:
+      type: object
+      required:
+        - type
+        - args
+      properties:
+        type:
+          type: string
+          enum:
+            - deleteProxy
+        args:
+          type: object
+          required:
+            - proxy
+          properties:
+            proxy:
+              $ref: '#/components/schemas/proxy'
+    BaseOp:
+      type: object
+      required:
+        - sig
+        - salt
+        - ts
+      properties:
+        sig:
+          $ref: '#/components/schemas/sig'
+        salt:
+          $ref: '#/components/schemas/salt'
+        ts:
+          $ref: '#/components/schemas/ts'
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    GenericRejected:
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    proxy:
+      type: string
+      description: Proxy address in hex format
+      example: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'
+    sig:
+      type: string
+      description: Signature in hex format
+      example: 0x1234567890...
+    salt:
+      type: integer
+      description: Salt
+      example: 1234567890
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error422Response:
+      description: |
+        Unprocessable Entity — the request was well-formed but a domain rule
+        rejected it on its merits (insufficient balance, invalid leverage,
+        proxy already exists, …). The body is the discriminated rejection
+        (`status: err`) with the engine error identifier in `error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/GenericRejected'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-account-limits.md

@@ -0,0 +1,242 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Account Limits
+
+> Get the authenticated account's effective rate-limit allowances for its current
+volume-based tier: order-action rate, open-order cap, and the display-only
+messages-per-minute figure. `open_orders` reflects the account's current live
+open-order count; the rate-usage counters (`actions_per_minute`,
+`actions_burst`, and `reset`) are not tracked here and are reported as 0.
+
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/limits
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/limits:
+    get:
+      summary: Get Account Limits
+      description: >
+        Get the authenticated account's effective rate-limit allowances for its
+        current
+
+        volume-based tier: order-action rate, open-order cap, and the
+        display-only
+
+        messages-per-minute figure. `open_orders` reflects the account's current
+        live
+
+        open-order count; the rate-usage counters (`actions_per_minute`,
+
+        `actions_burst`, and `reset`) are not tracked here and are reported as
+        0.
+      operationId: getAccountLimits
+      responses:
+        '200':
+          description: Account limits response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AccountLimits'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    AccountLimits:
+      type: object
+      required:
+        - actions_per_minute
+        - actions_per_minute_limit
+        - actions_burst
+        - actions_burst_limit
+        - open_orders
+        - open_orders_limit
+        - reset
+        - messages_per_minute
+      properties:
+        actions_per_minute:
+          $ref: '#/components/schemas/actions_per_minute'
+        actions_per_minute_limit:
+          $ref: '#/components/schemas/actions_per_minute_limit'
+        actions_burst:
+          $ref: '#/components/schemas/actions_burst'
+        actions_burst_limit:
+          $ref: '#/components/schemas/actions_burst_limit'
+        open_orders:
+          $ref: '#/components/schemas/open_orders'
+        open_orders_limit:
+          $ref: '#/components/schemas/open_orders_limit'
+        reset:
+          $ref: '#/components/schemas/rate_reset'
+        messages_per_minute:
+          $ref: '#/components/schemas/messages_per_minute'
+    actions_per_minute:
+      type: integer
+      description: Order action tokens used by the account in the current minute
+      example: 23
+    actions_per_minute_limit:
+      type: integer
+      description: Maximum order action tokens per account per minute
+      example: 300
+    actions_burst:
+      type: integer
+      description: Additional account action allowance remaining
+    actions_burst_limit:
+      type: integer
+      description: Additional account action allowance limit
+    open_orders:
+      type: integer
+      description: Current number of open orders
+      example: 42
+    open_orders_limit:
+      type: integer
+      description: Maximum number of open orders per account
+      example: 1000
+    rate_reset:
+      type: integer
+      description: Timestamp in milliseconds when the current interval resets
+      example: 1767225660000
+    messages_per_minute:
+      type: integer
+      description: >-
+        Display-only per-minute action/message allowance, equal to
+        actions_per_minute_limit. Not separately configured or enforced.
+      example: 300
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-account-referral.md

@@ -0,0 +1,207 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Account Referral
+
+> Get the authenticated account's invite code, parent referral code, direct
+referral count, and fee share rate.
+
+
+<Badge color="gray" size="md">Request Weight: **1**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/referral
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/referral:
+    get:
+      summary: Get Account Referral
+      description: >
+        Get the authenticated account's invite code, parent referral code,
+        direct
+
+        referral count, and fee share rate.
+      operationId: getAccountReferral
+      responses:
+        '200':
+          description: Account referral response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AccountReferral'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    AccountReferral:
+      type: object
+      required:
+        - code
+        - children_count
+        - referrals_left
+        - fee_share_rate
+      properties:
+        code:
+          $ref: '#/components/schemas/code'
+        parent:
+          $ref: '#/components/schemas/code'
+          description: >-
+            Parent referral code, omitted when the account has no parent
+            referral.
+        children_count:
+          $ref: '#/components/schemas/children_count'
+        referrals_left:
+          $ref: '#/components/schemas/referrals_left'
+        fee_share_rate:
+          $ref: '#/components/schemas/fee_share_rate'
+    code:
+      type: string
+      description: Referral or invite code
+      example: ABC123
+    children_count:
+      type: integer
+      description: Number of directly referred child accounts
+      example: 12
+    referrals_left:
+      type: integer
+      description: Number of additional referrals remaining for this account's invite code
+      example: 11
+    fee_share_rate:
+      type: string
+      description: Referral fee share rate. Defaults to 0.2.
+      example: '0.2'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-account-rewards.md

@@ -0,0 +1,333 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Account Rewards
+
+> Get per-instrument daily liquidity reward shares for the authenticated account.
+Reward periods run from 12:00 UTC to 12:00 UTC and are labeled by their UTC end date.
+OI rewards pay 6% APR on the account's full daily average gross OI across all
+instruments when the combined daily average gross OI of its rewards entity is
+at least $1M. Accounts without an entity mapping qualify independently.
+The first reward period starts at 2026-05-08 12:00 UTC. If no date range is provided,
+the latest computed reward period is returned.
+
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/rewards
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/rewards:
+    get:
+      summary: Get Account Rewards
+      description: >
+        Get per-instrument daily liquidity reward shares for the authenticated
+        account.
+
+        Reward periods run from 12:00 UTC to 12:00 UTC and are labeled by their
+        UTC end date.
+
+        OI rewards pay 6% APR on the account's full daily average gross OI
+        across all
+
+        instruments when the combined daily average gross OI of its rewards
+        entity is
+
+        at least $1M. Accounts without an entity mapping qualify independently.
+
+        The first reward period starts at 2026-05-08 12:00 UTC. If no date range
+        is provided,
+
+        the latest computed reward period is returned.
+      operationId: getAccountRewards
+      parameters:
+        - name: date
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/date'
+        - name: start_date
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/start_date'
+        - name: end_date
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/end_date'
+        - name: limit
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/limit'
+      responses:
+        '200':
+          description: Account rewards response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AccountRewards'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    date:
+      type: string
+      description: UTC reward period end date in YYYY-MM-DD format
+      example: '2026-05-10'
+    start_date:
+      type: string
+      description: Inclusive UTC start date in YYYY-MM-DD format
+      example: '2026-05-01'
+    end_date:
+      type: string
+      description: Inclusive UTC end date in YYYY-MM-DD format
+      example: '2026-05-10'
+    limit:
+      type: integer
+      description: Maximum number of entries to return
+      example: 100
+    AccountRewards:
+      type: object
+      required:
+        - data
+        - more
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/AccountReward'
+        more:
+          $ref: '#/components/schemas/more'
+    AccountReward:
+      type: object
+      required:
+        - date
+        - maker_share_7d
+        - reward_distributed
+        - breakdown
+      properties:
+        date:
+          $ref: '#/components/schemas/date'
+        maker_share_7d:
+          $ref: '#/components/schemas/maker_share_7d'
+        reward_distributed:
+          $ref: '#/components/schemas/reward_distributed'
+        breakdown:
+          type: array
+          items:
+            $ref: '#/components/schemas/AccountRewardInstrument'
+        oi_rewards:
+          $ref: '#/components/schemas/AccountRewardOi'
+    more:
+      type: boolean
+      description: More data available
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    maker_share_7d:
+      type: string
+      description: Rolling 7-day account maker volume divided by total exchange volume
+      example: '0.35'
+    reward_distributed:
+      type: boolean
+      description: Whether rewards for this period have been marked as distributed
+      example: true
+    AccountRewardInstrument:
+      type: object
+      required:
+        - instrument_id
+        - reward_pool
+        - reward_amount
+      properties:
+        instrument_id:
+          $ref: '#/components/schemas/instrument_id'
+        reward_pool:
+          $ref: '#/components/schemas/reward_pool'
+        reward_amount:
+          $ref: '#/components/schemas/reward_amount'
+    AccountRewardOi:
+      type: object
+      required:
+        - account_oi
+        - reward_amount
+      properties:
+        account_oi:
+          $ref: '#/components/schemas/account_oi'
+        reward_amount:
+          $ref: '#/components/schemas/reward_amount'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+    instrument_id:
+      type: integer
+      description: Instrument ID
+    reward_pool:
+      type: string
+      description: Configured reward pool for the instrument
+      example: '1000'
+    reward_amount:
+      type: string
+      description: Reward amount attributed to this reward row
+      example: '127.50344'
+    account_oi:
+      type: string
+      description: >-
+        Daily average gross open-interest notional for this account across all
+        instruments
+      example: '3200000'
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-account-stats.md

@@ -0,0 +1,223 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Account Stats
+
+> Get the authenticated account's 7-day trading stats (taker volume, maker volume,
+account maker share, and entity maker share when applicable).
+Stats are cached by UTC day and may be stale by up to 24 hours.
+
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/stats
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/stats:
+    get:
+      summary: Get Account Stats
+      description: >
+        Get the authenticated account's 7-day trading stats (taker volume, maker
+        volume,
+
+        account maker share, and entity maker share when applicable).
+
+        Stats are cached by UTC day and may be stale by up to 24 hours.
+      operationId: getAccountStats
+      responses:
+        '200':
+          description: Account stats response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AccountStats'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    AccountStats:
+      type: object
+      required:
+        - volume_7d
+        - taker_volume_7d
+        - maker_volume_7d
+        - account_maker_share_7d
+      properties:
+        volume_7d:
+          $ref: '#/components/schemas/volume_7d'
+        taker_volume_7d:
+          $ref: '#/components/schemas/taker_volume_7d'
+        maker_volume_7d:
+          $ref: '#/components/schemas/maker_volume_7d'
+        account_maker_share_7d:
+          $ref: '#/components/schemas/account_maker_share_7d'
+        entity_maker_share_7d:
+          $ref: '#/components/schemas/entity_maker_share_7d'
+        entity_id:
+          $ref: '#/components/schemas/entity_id'
+        entity_name:
+          $ref: '#/components/schemas/entity_name'
+    volume_7d:
+      type: string
+      description: Rolling 7-day perpetual trading volume in USD
+      example: '5000000'
+    taker_volume_7d:
+      type: string
+      description: Rolling 7-day perpetual taker volume in USD
+      example: '3500000'
+    maker_volume_7d:
+      type: string
+      description: Rolling 7-day perpetual maker volume in USD
+      example: '1500000'
+    account_maker_share_7d:
+      type: string
+      description: Rolling 7-day account maker volume divided by total exchange volume
+      example: '0.35'
+    entity_maker_share_7d:
+      type: string
+      description: Rolling 7-day entity maker volume divided by total exchange volume
+      example: '0.35'
+    entity_id:
+      type: integer
+      description: Liquidity rewards entity ID
+      example: 42
+    entity_name:
+      type: string
+      description: Liquidity rewards entity name
+      example: desk
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-auto-cancel-status.md

@@ -0,0 +1,210 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Auto-Cancel Status
+
+> Get the current auto-cancel dead-man-switch status for the authenticated
+account, including the armed deadline, today's trigger count, and when
+the daily counter resets.
+
+
+<Badge color="gray" size="md">Request Weight: **1**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/auto-cancel
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/auto-cancel:
+    get:
+      summary: Get Auto-Cancel Status
+      description: |
+        Get the current auto-cancel dead-man-switch status for the authenticated
+        account, including the armed deadline, today's trigger count, and when
+        the daily counter resets.
+      operationId: getAutoCancel
+      responses:
+        '200':
+          description: Auto-cancel status response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AutoCancelStatus'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    AutoCancelStatus:
+      type: object
+      required:
+        - deadline
+        - triggered
+        - daily_limit
+        - next_reset
+      properties:
+        deadline:
+          $ref: '#/components/schemas/auto_cancel_deadline'
+        triggered:
+          $ref: '#/components/schemas/auto_cancel_triggered'
+        daily_limit:
+          $ref: '#/components/schemas/auto_cancel_daily_limit'
+        next_reset:
+          $ref: '#/components/schemas/auto_cancel_next_reset'
+    auto_cancel_deadline:
+      type: integer
+      description: |
+        Unix-ms deadline for the per-account auto-cancel dead-man-switch.
+        Zero means no schedule is armed. When the deadline elapses, every
+        open order on the account is cancelled and the schedule clears.
+      example: 1767000045000
+    auto_cancel_triggered:
+      type: integer
+      description: |
+        Number of times auto-cancel has fired for this account during the
+        current UTC day. Resets to zero at 00:00 UTC.
+      example: 0
+    auto_cancel_daily_limit:
+      type: integer
+      description: |
+        Maximum number of auto-cancel triggers allowed per UTC day.
+      example: 10
+    auto_cancel_next_reset:
+      type: integer
+      description: |
+        Unix-ms timestamp of the next UTC midnight when the daily trigger
+        count resets to zero.
+      example: 1767052800000
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-balances.md

@@ -0,0 +1,191 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Balances
+
+> Get asset balances for the authenticated account.
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/balances
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/balances:
+    get:
+      summary: Get Balances
+      description: Get asset balances for the authenticated account.
+      operationId: getBalances
+      responses:
+        '200':
+          description: Balances response.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Balance'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    Balance:
+      type: object
+      required:
+        - asset
+        - balance
+        - value
+      properties:
+        asset:
+          $ref: '#/components/schemas/asset'
+        balance:
+          $ref: '#/components/schemas/balance'
+        value:
+          $ref: '#/components/schemas/value'
+    asset:
+      type: string
+      description: Asset name
+      example: USDC
+    balance:
+      type: string
+      description: Total balance
+      example: '10000.00'
+    value:
+      type: string
+      description: USD value
+      example: '10000.00'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-bbo.md

@@ -0,0 +1,211 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get BBO
+
+> Get best bid and offer for all instruments.
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/bbo
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/bbo:
+    get:
+      summary: Get BBO
+      description: Get best bid and offer for all instruments.
+      operationId: getBBO
+      parameters:
+        - name: instrument_id
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/instrument_id'
+      responses:
+        '200':
+          description: BBO response.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/BBO'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    instrument_id:
+      type: integer
+      description: Instrument ID
+    BBO:
+      title: BBO
+      type: object
+      required:
+        - instrument_id
+        - bid_price
+        - bid_quantity
+        - ask_price
+        - ask_quantity
+        - timestamp
+      properties:
+        instrument_id:
+          $ref: '#/components/schemas/iid'
+        bid_price:
+          $ref: '#/components/schemas/best_bid_price'
+        bid_quantity:
+          $ref: '#/components/schemas/best_bid_quantity'
+        ask_price:
+          $ref: '#/components/schemas/best_ask_price'
+        ask_quantity:
+          $ref: '#/components/schemas/best_ask_quantity'
+        timestamp:
+          $ref: '#/components/schemas/ts'
+    iid:
+      type: integer
+      description: Instrument ID
+      example: 1
+    best_bid_price:
+      type: string
+      description: Best bid price
+      example: '99.50'
+    best_bid_quantity:
+      type: string
+      description: Best bid quantity
+      example: '10.00'
+    best_ask_price:
+      type: string
+      description: Best ask price
+      example: '100.50'
+    best_ask_quantity:
+      type: string
+      description: Best ask quantity
+      example: '10.00'
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-book.md

@@ -0,0 +1,233 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Book
+
+> Get book for an instrument.
+
+<Badge color="gray" size="md">Request Weight:</Badge>
+
+<br />
+
+<Badge color="gray" size="md">Depth 10: **2**</Badge>
+
+<br />
+
+<Badge color="gray" size="md">Depth 100: **5**</Badge>
+
+<br />
+
+<Badge color="gray" size="md">Depth 500: **10**</Badge>
+
+<br />
+
+<Badge color="gray" size="md">Depth 1000: **20**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/book
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/book:
+    get:
+      summary: Get Book
+      description: Get book for an instrument.
+      operationId: getBook
+      parameters:
+        - name: instrument_id
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/instrument_id'
+        - name: depth
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/depth'
+      responses:
+        '200':
+          description: Book response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Book'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    instrument_id:
+      type: integer
+      description: Instrument ID
+    depth:
+      type: integer
+      description: Number of book levels to return
+      enum:
+        - 10
+        - 100
+        - 500
+        - 1000
+      default: 100
+    Book:
+      type: object
+      required:
+        - instrument_id
+        - bids
+        - asks
+        - timestamp
+        - sequence
+      properties:
+        instrument_id:
+          $ref: '#/components/schemas/instrument_id'
+        bids:
+          type: array
+          items:
+            $ref: '#/components/schemas/level'
+          description: Bid levels
+        asks:
+          type: array
+          items:
+            $ref: '#/components/schemas/level'
+          description: Ask levels
+        timestamp:
+          $ref: '#/components/schemas/timestamp'
+        sequence:
+          $ref: '#/components/schemas/sequence'
+    level:
+      type: array
+      items:
+        type: string
+      maxItems: 2
+      description: |
+        - `"100.00"` - Price
+        - `"10.00"` - Quantity
+      example:
+        - '100.00'
+        - '10.00'
+    timestamp:
+      type: integer
+      description: Timestamp in milliseconds
+      example: 1767225600000
+    sequence:
+      type: integer
+      description: Sequence number
+      example: 1234567890
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-collateral-assets.md

@@ -0,0 +1,169 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Collateral Assets
+
+> Get a list of collateral assets.
+
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/assets
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/assets:
+    get:
+      summary: Get Collateral Assets
+      description: |
+        Get a list of collateral assets.
+      operationId: getAssets
+      responses:
+        '200':
+          description: Assets response.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Asset'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    Asset:
+      type: object
+      required:
+        - asset
+        - address
+        - decimals
+        - collateral_ratio
+        - withdrawal_fee
+      properties:
+        asset:
+          $ref: '#/components/schemas/asset'
+        address:
+          $ref: '#/components/schemas/address'
+        decimals:
+          $ref: '#/components/schemas/decimals'
+        collateral_ratio:
+          $ref: '#/components/schemas/collateral_ratio'
+        withdrawal_fee:
+          $ref: '#/components/schemas/withdrawal_fee'
+    asset:
+      type: string
+      description: Asset name
+      example: USDC
+    address:
+      type: string
+      description: Address
+      example: '0x1234567890abcdef1234567890abcdef12345678'
+    decimals:
+      type: integer
+      description: Asset decimals
+      example: 6
+    collateral_ratio:
+      type: string
+      description: Collateral ratio
+      example: '1.00'
+    withdrawal_fee:
+      type: string
+      description: Withdrawal transaction fee in decimalized asset units
+      example: '5.00'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-credentials.md

@@ -0,0 +1,230 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Credentials
+
+> Get the account ID, address, and proxy keys for the authenticated account.
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/credentials
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/credentials:
+    get:
+      summary: Get Credentials
+      description: >-
+        Get the account ID, address, and proxy keys for the authenticated
+        account.
+      operationId: getCredentials
+      responses:
+        '200':
+          description: Credentials response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Credentials'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    Credentials:
+      type: object
+      required:
+        - address
+        - keys
+      properties:
+        address:
+          $ref: '#/components/schemas/address'
+        keys:
+          type: array
+          items:
+            $ref: '#/components/schemas/Key'
+    address:
+      type: string
+      description: Address
+      example: '0x1234567890abcdef1234567890abcdef12345678'
+    Key:
+      type: object
+      required:
+        - proxy
+        - expiry
+      properties:
+        proxy:
+          $ref: '#/components/schemas/proxy'
+        label:
+          $ref: '#/components/schemas/label'
+        expiry:
+          $ref: '#/components/schemas/expiry'
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    proxy:
+      type: string
+      description: Proxy address in hex format
+      example: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'
+    label:
+      type: string
+      description: Human-readable label for a proxy key or internal transfer
+      example: trading-bot
+    expiry:
+      type: integer
+      description: Expiry timestamp in milliseconds
+      example: 1767225600000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-deposits.md

@@ -0,0 +1,318 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Deposits
+
+> Get deposit history for the authenticated account.
+If no end time is provided, the current time will be used.
+Maximum of 100 entries returned per request.
+
+
+<Badge color="gray" size="md">Request Weight: **10**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/deposits
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/deposits:
+    get:
+      summary: Get Deposits
+      description: |
+        Get deposit history for the authenticated account.
+        If no end time is provided, the current time will be used.
+        Maximum of 100 entries returned per request.
+      operationId: getDeposits
+      parameters:
+        - name: deposit_status
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/deposit_status'
+        - name: hash
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/hash'
+        - name: start_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/start_timestamp'
+        - name: end_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/end_timestamp'
+      responses:
+        '200':
+          description: Deposit history response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Deposits'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    deposit_status:
+      type: string
+      description: Deposit status
+      enum:
+        - pending
+        - confirmed
+        - removed
+    hash:
+      type: string
+      description: On-chain transaction hash, "0x" if not yet mined
+      default: 0x
+      example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+    start_timestamp:
+      type: integer
+      description: Start timestamp in milliseconds
+      example: 1767225600000
+    end_timestamp:
+      type: integer
+      description: End timestamp in milliseconds
+      example: 1767229200000
+    Deposits:
+      type: object
+      required:
+        - data
+        - more
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/Deposit'
+        more:
+          $ref: '#/components/schemas/more'
+    Deposit:
+      type: object
+      required:
+        - hash
+        - asset
+        - amount
+        - status
+        - from
+        - to
+        - confirmations
+        - required_confirmations
+        - created_timestamp
+      properties:
+        hash:
+          $ref: '#/components/schemas/hash'
+        asset:
+          $ref: '#/components/schemas/asset'
+        amount:
+          $ref: '#/components/schemas/amount'
+        from:
+          $ref: '#/components/schemas/from'
+        to:
+          $ref: '#/components/schemas/to'
+        status:
+          $ref: '#/components/schemas/deposit_status'
+        confirmations:
+          $ref: '#/components/schemas/confirmations'
+        required_confirmations:
+          $ref: '#/components/schemas/required_confirmations'
+        created_timestamp:
+          $ref: '#/components/schemas/created_timestamp'
+        confirmed_timestamp:
+          $ref: '#/components/schemas/confirmed_timestamp'
+    more:
+      type: boolean
+      description: More data available
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    asset:
+      type: string
+      description: Asset name
+      example: USDC
+    amount:
+      type: string
+      description: >-
+        Raw token amount including decimals. For withdrawals this matches the
+        uint256 amount in the EIP-712 signature (e.g. "100000000" for 100 USDC
+        with 6 decimals).
+      example: '100000000'
+    from:
+      type: string
+      description: Sender address in hex format
+      example: '0x1234567890abcdef1234567890abcdef12345678'
+    to:
+      type: string
+      description: Destination address in hex format
+      example: '0x1234567890abcdef1234567890abcdef12345678'
+    confirmations:
+      type: integer
+      description: Number of block confirmations
+      example: 12
+    required_confirmations:
+      type: integer
+      description: Required number of block confirmations
+      example: 12
+    created_timestamp:
+      type: integer
+      description: Creation timestamp in milliseconds
+      example: 1767225600000
+    confirmed_timestamp:
+      type: integer
+      description: Confirmation timestamp in milliseconds
+      example: 1767225600000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-equity.md

@@ -0,0 +1,255 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Equity
+
+> Get equity history for the authenticated account.
+If no end time is provided, the current time will be used.
+Maximum of 1000 entries returned per request.
+
+
+<Badge color="gray" size="md">Request Weight: **10**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/equity
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/equity:
+    get:
+      summary: Get Equity
+      description: |
+        Get equity history for the authenticated account.
+        If no end time is provided, the current time will be used.
+        Maximum of 1000 entries returned per request.
+      operationId: getEquityHistory
+      parameters:
+        - name: interval
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/interval'
+        - name: start_timestamp
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/start_timestamp'
+        - name: end_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/end_timestamp'
+      responses:
+        '200':
+          description: Equity history response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EquityHistory'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    interval:
+      type: string
+      description: Kline interval
+      enum:
+        - 1s
+        - 1m
+        - 5m
+        - 15m
+        - 30m
+        - 1h
+        - 4h
+        - 6h
+        - 12h
+        - 1d
+        - 1w
+    start_timestamp:
+      type: integer
+      description: Start timestamp in milliseconds
+      example: 1767225600000
+    end_timestamp:
+      type: integer
+      description: End timestamp in milliseconds
+      example: 1767229200000
+    EquityHistory:
+      type: object
+      required:
+        - data
+        - more
+      properties:
+        data:
+          type: array
+          description: |
+            - `1767225600000` - Timestamp
+            - `"10000.00"` - Equity
+          items:
+            type: array
+            example:
+              - 1767225600000
+              - '10000.00'
+          maxItems: 1000
+        more:
+          $ref: '#/components/schemas/more'
+    more:
+      type: boolean
+      description: More data available
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-exchange-info.md

@@ -0,0 +1,161 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Exchange Info
+
+> Get exchange information.
+
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/exchange
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/exchange:
+    get:
+      summary: Get Exchange Info
+      description: |
+        Get exchange information.
+      operationId: getExchange
+      responses:
+        '200':
+          description: Successful exchange information response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Exchange'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    Exchange:
+      type: object
+      required:
+        - name
+        - version
+        - chain_id
+        - contract
+      properties:
+        name:
+          $ref: '#/components/schemas/name'
+        version:
+          $ref: '#/components/schemas/version'
+        chain_id:
+          $ref: '#/components/schemas/chain_id'
+        contract:
+          $ref: '#/components/schemas/contract'
+    name:
+      type: string
+      description: Exchange name used in the EIP-712 domain.
+      example: Polymarket
+    version:
+      type: string
+      description: Exchange version used in the EIP-712 domain.
+      example: '1'
+    chain_id:
+      type: integer
+      format: uint32
+      description: Chain ID of the network the exchange is deployed on.
+      example: 137
+    contract:
+      type: string
+      description: Verifying contract address or the EIP-712 domain.
+      example: '0x1234567890abcdef1234567890abcdef12345678'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-fees.md

@@ -0,0 +1,179 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Fees
+
+> Get the default fee schedule for each instrument type and category. Rates returned are the $0-tier defaults; the account's actual rate on each fill depends on its trailing 30-day volume tier.
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/fees
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/fees:
+    get:
+      summary: Get Fees
+      description: >-
+        Get the default fee schedule for each instrument type and category.
+        Rates returned are the $0-tier defaults; the account's actual rate on
+        each fill depends on its trailing 30-day volume tier.
+      operationId: getInfoFees
+      responses:
+        '200':
+          description: Fee schedule response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FeesInfo'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    FeesInfo:
+      type: object
+      required:
+        - fee_schedule
+      properties:
+        fee_schedule:
+          type: array
+          items:
+            $ref: '#/components/schemas/FeeScheduleEntry'
+    FeeScheduleEntry:
+      type: object
+      required:
+        - instrument_type
+        - category
+        - taker_fee_rate
+        - maker_fee_rate
+      properties:
+        instrument_type:
+          $ref: '#/components/schemas/instrument_type'
+        category:
+          $ref: '#/components/schemas/category'
+        taker_fee_rate:
+          $ref: '#/components/schemas/taker_fee_rate'
+        maker_fee_rate:
+          $ref: '#/components/schemas/maker_fee_rate'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    instrument_type:
+      type: string
+      description: Instrument type
+      enum:
+        - perpetual
+    category:
+      type: string
+      description: Instrument category
+      enum:
+        - equity
+        - commodity
+        - index
+        - crypto
+    taker_fee_rate:
+      type: string
+      description: >-
+        Default taker fee rate for the $0 volume tier. Actual rate scales down
+        with the account's trailing 30-day volume tier.
+      example: '0.0004'
+    maker_fee_rate:
+      type: string
+      description: >-
+        Default maker fee rate for the $0 volume tier. Positive at lower tiers,
+        zero at the $500M tier, and a rebate (negative) at the top tier.
+      example: '0.000125'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-fills.md

@@ -0,0 +1,342 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Fills
+
+> Get fill history for the authenticated account.
+If no end time is provided, the current time will be used.
+Maximum of 100 entries returned per request.
+
+
+<Badge color="gray" size="md">Request Weight: **10**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/fills
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/fills:
+    get:
+      summary: Get Fills
+      description: |
+        Get fill history for the authenticated account.
+        If no end time is provided, the current time will be used.
+        Maximum of 100 entries returned per request.
+      operationId: getFills
+      parameters:
+        - name: start_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/start_timestamp'
+        - name: end_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/end_timestamp'
+      responses:
+        '200':
+          description: Fills response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AccountTrades'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    start_timestamp:
+      type: integer
+      description: Start timestamp in milliseconds
+      example: 1767225600000
+    end_timestamp:
+      type: integer
+      description: End timestamp in milliseconds
+      example: 1767229200000
+    AccountTrades:
+      type: object
+      required:
+        - data
+        - more
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/AccountTradeData'
+          description: Account's trade history
+        more:
+          $ref: '#/components/schemas/more'
+    AccountTradeData:
+      type: object
+      required:
+        - trade_id
+        - order_id
+        - instrument_id
+        - side
+        - price
+        - quantity
+        - taker
+        - fee
+        - fee_asset
+        - previous_size
+        - previous_entry_price
+        - pnl
+        - timestamp
+        - liquidation
+        - hash
+      properties:
+        trade_id:
+          $ref: '#/components/schemas/tid'
+        order_id:
+          $ref: '#/components/schemas/oid'
+        instrument_id:
+          $ref: '#/components/schemas/iid'
+        side:
+          $ref: '#/components/schemas/side'
+        price:
+          $ref: '#/components/schemas/p'
+        quantity:
+          $ref: '#/components/schemas/qty'
+        taker:
+          $ref: '#/components/schemas/taker'
+        fee:
+          $ref: '#/components/schemas/fee'
+        fee_asset:
+          $ref: '#/components/schemas/fea'
+        previous_size:
+          $ref: '#/components/schemas/psz'
+        previous_entry_price:
+          $ref: '#/components/schemas/pep'
+        pnl:
+          $ref: '#/components/schemas/pnl'
+        liquidation:
+          $ref: '#/components/schemas/liq'
+        timestamp:
+          $ref: '#/components/schemas/ts'
+        hash:
+          $ref: '#/components/schemas/hash'
+    more:
+      type: boolean
+      description: More data available
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    tid:
+      type: integer
+      description: Trade ID
+      example: 1
+    oid:
+      type: integer
+      description: Order ID
+      example: 1234567890
+    iid:
+      type: integer
+      description: Instrument ID
+      example: 1
+    side:
+      type: string
+      description: Side
+      enum:
+        - long
+        - short
+    p:
+      type: string
+      description: Price
+      example: '100.00'
+    qty:
+      type: string
+      description: Quantity in no. of contracts
+      example: '10.00'
+    taker:
+      type: boolean
+      description: Whether this side was the taker
+    fee:
+      type: string
+      description: Fee amount for this trade side
+      example: '1.25'
+    fea:
+      type: string
+      description: Fee asset name
+      example: USDC
+    psz:
+      type: string
+      description: Position size before the fill
+      example: '26.86'
+    pep:
+      type: string
+      description: Position entry price before the fill
+      example: '100.00'
+    pnl:
+      type: string
+      description: PnL in USD
+      example: '100.00'
+    liq:
+      type: boolean
+      description: Whether the fill was a liquidation
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+    hash:
+      type: string
+      description: On-chain transaction hash, "0x" if not yet mined
+      default: 0x
+      example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-funding-charges.md

@@ -0,0 +1,287 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Funding Charges
+
+> Get funding payment history for the authenticated account.
+If no end time is provided, the current time will be used.
+Maximum of 100 entries returned per request.
+
+
+<Badge color="gray" size="md">Request Weight: **10**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/funding
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/funding:
+    get:
+      summary: Get Funding Charges
+      description: |
+        Get funding payment history for the authenticated account.
+        If no end time is provided, the current time will be used.
+        Maximum of 100 entries returned per request.
+      operationId: getAccountFunding
+      parameters:
+        - name: instrument_id
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/instrument_id'
+        - name: start_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/start_timestamp'
+        - name: end_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/end_timestamp'
+      responses:
+        '200':
+          description: Account funding history response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AccountFundingHistory'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    instrument_id:
+      type: integer
+      description: Instrument ID
+    start_timestamp:
+      type: integer
+      description: Start timestamp in milliseconds
+      example: 1767225600000
+    end_timestamp:
+      type: integer
+      description: End timestamp in milliseconds
+      example: 1767229200000
+    AccountFundingHistory:
+      type: object
+      required:
+        - data
+        - more
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/AccountFundingData'
+        more:
+          $ref: '#/components/schemas/more'
+    AccountFundingData:
+      type: object
+      required:
+        - instrument_id
+        - size
+        - funding_rate
+        - funding_asset
+        - funding
+        - timestamp
+      properties:
+        instrument_id:
+          $ref: '#/components/schemas/iid'
+        size:
+          $ref: '#/components/schemas/sz'
+        funding_rate:
+          $ref: '#/components/schemas/fr'
+        funding_asset:
+          $ref: '#/components/schemas/fua'
+        funding:
+          $ref: '#/components/schemas/fund'
+        timestamp:
+          $ref: '#/components/schemas/ts'
+    more:
+      type: boolean
+      description: More data available
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    iid:
+      type: integer
+      description: Instrument ID
+      example: 1
+    sz:
+      type: string
+      description: >-
+        Signed position size in no. of contracts (positive = long, negative =
+        short)
+      example: '10.00'
+    fr:
+      type: string
+      description: Funding rate
+      example: '0.0001'
+    fua:
+      type: string
+      description: Funding asset name
+      example: USDC
+    fund:
+      type: string
+      description: Funding paid in USD
+      example: '1.00'
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-historical-funding.md

@@ -0,0 +1,217 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Historical Funding
+
+> Get public funding rate history for an instrument.
+Maximum of 100 entries returned per request.
+
+
+<Badge color="gray" size="md">Request Weight: **10**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/funding
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/funding:
+    get:
+      summary: Get Historical Funding
+      description: |
+        Get public funding rate history for an instrument.
+        Maximum of 100 entries returned per request.
+      operationId: getFundingHistory
+      parameters:
+        - name: instrument_id
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/instrument_id'
+        - name: start_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/start_timestamp'
+        - name: end_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/end_timestamp'
+      responses:
+        '200':
+          description: Funding rate history response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FundingHistory'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    instrument_id:
+      type: integer
+      description: Instrument ID
+    start_timestamp:
+      type: integer
+      description: Start timestamp in milliseconds
+      example: 1767225600000
+    end_timestamp:
+      type: integer
+      description: End timestamp in milliseconds
+      example: 1767229200000
+    FundingHistory:
+      type: object
+      required:
+        - data
+        - more
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/FundingRate'
+        more:
+          $ref: '#/components/schemas/more'
+    FundingRate:
+      type: object
+      required:
+        - funding_rate
+        - timestamp
+      properties:
+        funding_rate:
+          $ref: '#/components/schemas/fr'
+        timestamp:
+          $ref: '#/components/schemas/ts'
+    more:
+      type: boolean
+      description: More data available
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    fr:
+      type: string
+      description: Funding rate
+      example: '0.0001'
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-index.md

@@ -0,0 +1,233 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Index
+
+> Get index price and the list of constituents for an asset.
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/index
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/index:
+    get:
+      summary: Get Index
+      description: Get index price and the list of constituents for an asset.
+      operationId: getIndex
+      parameters:
+        - name: asset
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/asset'
+      responses:
+        '200':
+          description: Index constituents response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Index'
+              examples:
+                index:
+                  summary: Index constituents
+                  value:
+                    asset: NVDA
+                    index_price: '160.00'
+                    constituents:
+                      - source: chainlink
+                        symbol: NVDA/USD
+                        weight: '1.0'
+                        price: '160.00'
+                    ts: 1767225600000
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    asset:
+      type: string
+      description: Asset name
+      example: USDC
+    Index:
+      type: object
+      required:
+        - asset
+        - index_price
+        - constituents
+        - ts
+      properties:
+        asset:
+          $ref: '#/components/schemas/asset'
+        index_price:
+          $ref: '#/components/schemas/index_price'
+        constituents:
+          type: array
+          items:
+            $ref: '#/components/schemas/IndexConstituent'
+        ts:
+          $ref: '#/components/schemas/ts'
+    index_price:
+      type: string
+      description: Index price
+      example: '100.00'
+    IndexConstituent:
+      type: object
+      required:
+        - source
+        - symbol
+        - weight
+        - price
+      properties:
+        source:
+          $ref: '#/components/schemas/source'
+        symbol:
+          $ref: '#/components/schemas/symbol'
+        weight:
+          $ref: '#/components/schemas/weight'
+        price:
+          $ref: '#/components/schemas/price'
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    source:
+      type: string
+      description: Source name
+      example: chainlink
+    symbol:
+      type: string
+      description: Instrument symbol
+      example: NVDA-USDC
+    weight:
+      type: string
+      description: Index constituent weight
+      example: '0.25'
+    price:
+      type: string
+      description: Price
+      example: '100.00'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-instrument-config.md

@@ -0,0 +1,226 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Instrument Config
+
+> Get per-instrument configuration (leverage and margin mode) for the authenticated account.
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/config
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/config:
+    get:
+      summary: Get Instrument Config
+      description: >-
+        Get per-instrument configuration (leverage and margin mode) for the
+        authenticated account.
+      operationId: getConfig
+      parameters:
+        - name: instrument_id
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/instrument_id'
+      responses:
+        '200':
+          description: Instrument config response.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/AccountConfig'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    instrument_id:
+      type: integer
+      description: Instrument ID
+    AccountConfig:
+      description: Account configuration.
+      type: object
+      required:
+        - instrument_id
+        - leverage
+        - cross
+      properties:
+        instrument_id:
+          $ref: '#/components/schemas/iid'
+        leverage:
+          $ref: '#/components/schemas/lev'
+        cross:
+          $ref: '#/components/schemas/cross'
+    iid:
+      type: integer
+      description: Instrument ID
+      example: 1
+    lev:
+      type: integer
+      description: Leverage
+      example: 10
+    cross:
+      type: boolean
+      description: Whether to use cross margin mode
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-instruments.md

@@ -0,0 +1,310 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Instruments
+
+> Get all instruments.
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/instruments
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/instruments:
+    get:
+      summary: Get Instruments
+      description: Get all instruments.
+      operationId: getInstruments
+      parameters:
+        - name: instrument_id
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/instrument_id'
+        - name: instrument_type
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/instrument_type'
+        - name: category
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/category'
+      responses:
+        '200':
+          description: Instruments response.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Instrument'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    instrument_id:
+      type: integer
+      description: Instrument ID
+    instrument_type:
+      type: string
+      description: Instrument type
+      enum:
+        - perpetual
+    category:
+      type: string
+      description: Instrument category
+      enum:
+        - equity
+        - commodity
+        - index
+        - crypto
+    Instrument:
+      type: object
+      required:
+        - instrument_id
+        - instrument_type
+        - category
+        - symbol
+        - base_asset
+        - quote_asset
+        - funding_interval
+        - quantity_decimals
+        - price_decimals
+        - price_bounds
+        - liquidation_fee
+        - max_order_count
+        - min_notional
+        - max_market_notional
+        - max_limit_notional
+        - max_leverage
+        - risk_tiers
+      properties:
+        instrument_id:
+          $ref: '#/components/schemas/instrument_id'
+        instrument_type:
+          $ref: '#/components/schemas/instrument_type'
+        category:
+          $ref: '#/components/schemas/category'
+        symbol:
+          $ref: '#/components/schemas/symbol'
+        base_asset:
+          $ref: '#/components/schemas/base_asset'
+        quote_asset:
+          $ref: '#/components/schemas/quote_asset'
+        funding_interval:
+          $ref: '#/components/schemas/funding_interval'
+        quantity_decimals:
+          $ref: '#/components/schemas/quantity_decimals'
+        price_decimals:
+          $ref: '#/components/schemas/price_decimals'
+        price_bounds:
+          $ref: '#/components/schemas/price_bounds'
+        liquidation_fee:
+          $ref: '#/components/schemas/liquidation_fee'
+        max_order_count:
+          $ref: '#/components/schemas/max_order_count'
+        min_notional:
+          $ref: '#/components/schemas/min_notional'
+        max_market_notional:
+          $ref: '#/components/schemas/max_market_notional'
+        max_limit_notional:
+          $ref: '#/components/schemas/max_limit_notional'
+        max_leverage:
+          $ref: '#/components/schemas/max_leverage'
+        risk_tiers:
+          type: array
+          items:
+            $ref: '#/components/schemas/RiskTier'
+    symbol:
+      type: string
+      description: Instrument symbol
+      example: NVDA-USDC
+    base_asset:
+      type: string
+      description: Base asset name
+      example: NVDA
+    quote_asset:
+      type: string
+      description: Quote asset name
+      example: USDC
+    funding_interval:
+      type: string
+      description: Funding interval
+      example: 1h
+    quantity_decimals:
+      type: integer
+      description: Number of decimal places for quantity.
+      example: 2
+    price_decimals:
+      type: integer
+      description: >-
+        Number of decimal places for price. Non-integer prices have a maximum of
+        5 significant figures; integer prices are allowed regardless of
+        significant figures.
+      example: 2
+    price_bounds:
+      type: string
+      description: Price bounds percentage
+      example: '0.05'
+    liquidation_fee:
+      type: string
+      description: Liquidation fee rate
+      example: '0.025'
+    max_order_count:
+      type: integer
+      description: Maximum open order count
+      example: 200
+    min_notional:
+      type: string
+      description: Minimum notional value in USD
+      example: '1.00'
+    max_market_notional:
+      type: string
+      description: Maximum market order notional value in USD
+      example: '1000000.00'
+    max_limit_notional:
+      type: string
+      description: Maximum limit order notional value in USD
+      example: '10000000.00'
+    max_leverage:
+      type: integer
+      description: Maximum leverage
+      example: 20
+    RiskTier:
+      type: object
+      required:
+        - lower_bound
+        - max_leverage
+      properties:
+        lower_bound:
+          $ref: '#/components/schemas/lower_bound'
+        max_leverage:
+          $ref: '#/components/schemas/max_leverage'
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    lower_bound:
+      type: string
+      description: Position size lower bound
+      example: '0'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-internal-transfers.md

@@ -0,0 +1,282 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Internal Transfers
+
+> Get settled internal transfer history for the authenticated account.
+Returns both inbound and outbound transfers.
+
+
+<Badge color="gray" size="md">Request Weight: **10**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/internal-transfers
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/internal-transfers:
+    get:
+      summary: Get Internal Transfers
+      description: |
+        Get settled internal transfer history for the authenticated account.
+        Returns both inbound and outbound transfers.
+      operationId: getInternalTransfers
+      parameters:
+        - name: start_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/start_timestamp'
+        - name: end_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/end_timestamp'
+      responses:
+        '200':
+          description: Internal transfer history response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InternalTransfers'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    start_timestamp:
+      type: integer
+      description: Start timestamp in milliseconds
+      example: 1767225600000
+    end_timestamp:
+      type: integer
+      description: End timestamp in milliseconds
+      example: 1767229200000
+    InternalTransfers:
+      type: object
+      required:
+        - data
+        - more
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/InternalTransfer'
+        more:
+          $ref: '#/components/schemas/more'
+    InternalTransfer:
+      type: object
+      required:
+        - transfer_id
+        - asset
+        - amount
+        - direction
+        - counterparty
+        - created_timestamp
+      properties:
+        transfer_id:
+          $ref: '#/components/schemas/transfer_id'
+        asset:
+          $ref: '#/components/schemas/asset'
+        amount:
+          $ref: '#/components/schemas/amount'
+        direction:
+          $ref: '#/components/schemas/direction'
+        counterparty:
+          $ref: '#/components/schemas/counterparty'
+        label:
+          $ref: '#/components/schemas/label'
+        created_timestamp:
+          $ref: '#/components/schemas/created_timestamp'
+    more:
+      type: boolean
+      description: More data available
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    transfer_id:
+      type: integer
+      description: Internal transfer ID
+    asset:
+      type: string
+      description: Asset name
+      example: USDC
+    amount:
+      type: string
+      description: >-
+        Raw token amount including decimals. For withdrawals this matches the
+        uint256 amount in the EIP-712 signature (e.g. "100000000" for 100 USDC
+        with 6 decimals).
+      example: '100000000'
+    direction:
+      type: string
+      description: Transfer direction relative to the authenticated account
+      enum:
+        - in
+        - out
+    counterparty:
+      type: string
+      description: Counterparty account address in hex format
+      example: '0x1234567890abcdef1234567890abcdef12345678'
+    label:
+      type: string
+      description: Human-readable label for a proxy key or internal transfer
+      example: trading-bot
+    created_timestamp:
+      type: integer
+      description: Creation timestamp in milliseconds
+      example: 1767225600000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-klines.md

@@ -0,0 +1,237 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Klines
+
+> Get klines for an instrument.
+If no end time is provided, the current time will be used.
+Maximum of 1000 entries returned per request.
+
+
+<Badge color="gray" size="md">Request Weight: **5**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/klines
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/klines:
+    get:
+      summary: Get Klines
+      description: |
+        Get klines for an instrument.
+        If no end time is provided, the current time will be used.
+        Maximum of 1000 entries returned per request.
+      operationId: getKlines
+      parameters:
+        - name: instrument_id
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/instrument_id'
+        - name: interval
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/interval'
+        - name: start_timestamp
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/start_timestamp'
+        - name: end_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/end_timestamp'
+      responses:
+        '200':
+          description: Klines response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/KlinesResponse'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    instrument_id:
+      type: integer
+      description: Instrument ID
+    interval:
+      type: string
+      description: Kline interval
+      enum:
+        - 1s
+        - 1m
+        - 5m
+        - 15m
+        - 30m
+        - 1h
+        - 4h
+        - 6h
+        - 12h
+        - 1d
+        - 1w
+    start_timestamp:
+      type: integer
+      description: Start timestamp in milliseconds
+      example: 1767225600000
+    end_timestamp:
+      type: integer
+      description: End timestamp in milliseconds
+      example: 1767229200000
+    KlinesResponse:
+      type: object
+      required:
+        - data
+        - more
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/kline'
+          maxItems: 1000
+        more:
+          $ref: '#/components/schemas/more'
+    kline:
+      type: array
+      description: |
+        - `1767225600000` - Open time
+        - `"100.00"` - Open price
+        - `"105.00"` - High price
+        - `"99.00"` - Low price
+        - `"102.00"` - Close price
+        - `"500.00"` - Volume (base unit)
+        - `42` - Number of trades
+      example:
+        - 1767225600000
+        - '100.00'
+        - '105.00'
+        - '99.00'
+        - '102.00'
+        - '500.00'
+        - 42
+    more:
+      type: boolean
+      description: More data available
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-limit-tiers.md

@@ -0,0 +1,188 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Limit Tiers
+
+> Get the list of account limit tiers. Action and open-order fields are enforced per account; legacy request-rate fields are not used for gateway request enforcement.
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/limit-tiers
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/limit-tiers:
+    get:
+      summary: Get Limit Tiers
+      description: >-
+        Get the list of account limit tiers. Action and open-order fields are
+        enforced per account; legacy request-rate fields are not used for
+        gateway request enforcement.
+      operationId: getLimitTiers
+      responses:
+        '200':
+          description: Limit tiers response.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/LimitTier'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    LimitTier:
+      type: object
+      required:
+        - min_volume_14d
+        - rate_per_minute_limit
+        - rate_burst_limit
+        - actions_per_minute_limit
+        - actions_burst_limit
+        - open_orders_limit
+        - messages_per_minute
+      properties:
+        min_volume_14d:
+          $ref: '#/components/schemas/min_volume'
+        rate_per_minute_limit:
+          $ref: '#/components/schemas/rate_per_minute_limit'
+        rate_burst_limit:
+          $ref: '#/components/schemas/rate_burst_limit'
+        actions_per_minute_limit:
+          $ref: '#/components/schemas/actions_per_minute_limit'
+        actions_burst_limit:
+          $ref: '#/components/schemas/actions_burst_limit'
+        open_orders_limit:
+          $ref: '#/components/schemas/open_orders_limit'
+        messages_per_minute:
+          $ref: '#/components/schemas/messages_per_minute'
+    min_volume:
+      type: string
+      description: Minimum volume threshold for this tier
+      example: '0'
+    rate_per_minute_limit:
+      type: integer
+      description: >-
+        Maximum IP request weight per minute. In limit tiers, this is a legacy
+        field and is not used for gateway enforcement.
+      example: 1200
+    rate_burst_limit:
+      type: integer
+      description: >-
+        Legacy limit-tier request-rate field. It is not used for gateway
+        enforcement.
+    actions_per_minute_limit:
+      type: integer
+      description: Maximum order action tokens per account per minute
+      example: 300
+    actions_burst_limit:
+      type: integer
+      description: Additional account action allowance limit
+    open_orders_limit:
+      type: integer
+      description: Maximum number of open orders per account
+      example: 1000
+    messages_per_minute:
+      type: integer
+      description: >-
+        Display-only per-minute action/message allowance, equal to
+        actions_per_minute_limit. Not separately configured or enforced.
+      example: 300
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-open-orders.md

@@ -0,0 +1,382 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Open Orders
+
+> Get open orders for the authenticated account.
+
+<Badge color="gray" size="md">Request Weight:</Badge>
+
+<br />
+
+<Badge color="gray" size="md">With instrument ID: **1**</Badge>
+
+<br />
+
+<Badge color="gray" size="md">Without instrument ID: **20**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/open-orders
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/open-orders:
+    get:
+      summary: Get Open Orders
+      description: Get open orders for the authenticated account.
+      operationId: getOpenOrders
+      parameters:
+        - name: instrument_id
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/iid'
+      responses:
+        '200':
+          description: Orders response.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/OrderData'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    iid:
+      type: integer
+      description: Instrument ID
+      example: 1
+    OrderData:
+      type: object
+      required:
+        - order_id
+        - instrument_id
+        - buy
+        - price
+        - quantity
+        - tif
+        - post_only
+        - ro
+        - status
+        - resting_quantity
+        - filled_quantity
+        - created_timestamp
+        - updated_timestamp
+      properties:
+        order_id:
+          $ref: '#/components/schemas/oid'
+        instrument_id:
+          $ref: '#/components/schemas/iid'
+        buy:
+          $ref: '#/components/schemas/buy'
+        price:
+          $ref: '#/components/schemas/p'
+        quantity:
+          $ref: '#/components/schemas/qty'
+        tif:
+          $ref: '#/components/schemas/tif'
+        post_only:
+          $ref: '#/components/schemas/po'
+        ro:
+          $ref: '#/components/schemas/ro'
+        resting_quantity:
+          $ref: '#/components/schemas/rest'
+        filled_quantity:
+          $ref: '#/components/schemas/fill'
+        status:
+          $ref: '#/components/schemas/st'
+        created_timestamp:
+          $ref: '#/components/schemas/cts'
+        updated_timestamp:
+          $ref: '#/components/schemas/uts'
+        client_order_id:
+          $ref: '#/components/schemas/coid'
+        tpsl:
+          $ref: '#/components/schemas/TpSlOrderFields'
+          description: >-
+            Conditional-order fields. Present only when the order is a TP/SL
+            conditional order — `null`/omitted for regular orders.
+    oid:
+      type: integer
+      description: Order ID
+      example: 1234567890
+    buy:
+      type: boolean
+      description: Is buy
+      example: true
+    p:
+      type: string
+      description: Price
+      example: '100.00'
+    qty:
+      type: string
+      description: Quantity in no. of contracts
+      example: '10.00'
+    tif:
+      type: string
+      description: Time in force
+      enum:
+        - gtc
+        - ioc
+        - fok
+    po:
+      type: boolean
+      description: Post only
+      default: false
+      example: false
+    ro:
+      type: boolean
+      description: Reduce only
+      example: false
+      default: false
+    rest:
+      type: string
+      description: Resting quantity
+      example: '9.00'
+    fill:
+      type: string
+      description: Filled quantity
+      example: '1.00'
+    st:
+      type: string
+      description: Order status
+      example: open
+    cts:
+      type: integer
+      description: Create timestamp in milliseconds
+      example: 1767225600000
+    uts:
+      type: integer
+      description: Update timestamp in milliseconds
+      example: 1767225600000
+    coid:
+      type: string
+      description: Client order ID
+      minLength: 32
+      maxLength: 32
+      pattern: ^[0-9a-f]{32}$
+      example: 550e8400e29b41d4a716446655440000
+    TpSlOrderFields:
+      type: object
+      description: TP/SL-specific fields surfaced alongside the regular order shape.
+      required:
+        - kind
+        - scope
+        - trp
+      properties:
+        kind:
+          $ref: '#/components/schemas/kind'
+        scope:
+          $ref: '#/components/schemas/tr_scope'
+        trp:
+          $ref: '#/components/schemas/trp'
+        parent_oid:
+          $ref: '#/components/schemas/parent_oid'
+        armed_qty:
+          $ref: '#/components/schemas/qty'
+          description: >-
+            Quantity armed at attach time (OCO) or `"0"` for position-based
+            (sized at trigger time).
+        slip_bps:
+          $ref: '#/components/schemas/slip_bps'
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    kind:
+      type: string
+      description: Conditional order type (TakeProfit / StopLoss)
+      enum:
+        - tp
+        - sl
+    tr_scope:
+      type: string
+      description: >
+        How the conditional order sizes itself.
+
+        - `order` - child of a parent entry (bracket / OCO ladder). Quantity is
+        required.
+
+        - `position` - attached to an open position. v1 always closes the full
+        position (`qty` must be `"0"`).
+      enum:
+        - order
+        - position
+    trp:
+      type: string
+      description: Trigger price
+      example: '110.00'
+    parent_oid:
+      type: integer
+      description: >-
+        Parent entry order id. Optional — omit it (do not send `0`) when the
+        parent is created in the same request (inline `CreateOrder.tpsl` or
+        `CreateTpSlArgs.parent`); the gateway auto-wires the child to it. Set it
+        only to attach an order-scoped leg to an existing resting order. Inline
+        `CreateOrder.tpsl` rejects a non-zero value; position-scoped legs carry
+        no parent.
+      example: 1234567890
+    slip_bps:
+      type: integer
+      minimum: 0
+      maximum: 10000
+      description: >-
+        Per-order market-trigger slippage cap in basis points. 0 = use the
+        per-instrument default. Clamped to the instrument cap.
+      example: 1000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-orders.md

@@ -0,0 +1,427 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Orders
+
+> Get historical order snapshots for the authenticated account from the order history database.
+Returns the latest known state for each matching order, including accepted, open, partial,
+filled, and cancelled orders. For currently resting orders only, use Get Open Orders.
+Maximum of 100 entries returned per request.
+
+
+<Badge color="gray" size="md">Request Weight:</Badge>
+
+<br />
+
+<Badge color="gray" size="md">With order ID: **1**</Badge>
+
+<br />
+
+<Badge color="gray" size="md">Without order ID: **10**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/orders
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/orders:
+    get:
+      summary: Get Orders
+      description: >
+        Get historical order snapshots for the authenticated account from the
+        order history database.
+
+        Returns the latest known state for each matching order, including
+        accepted, open, partial,
+
+        filled, and cancelled orders. For currently resting orders only, use Get
+        Open Orders.
+
+        Maximum of 100 entries returned per request.
+      operationId: getOrders
+      parameters:
+        - name: order_id
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/order_id'
+        - name: client_order_id
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/coid'
+        - name: instrument_id
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/iid'
+        - name: start_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/start_timestamp'
+        - name: end_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/end_timestamp'
+      responses:
+        '200':
+          description: Orders response.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/OrderData'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    order_id:
+      type: integer
+      description: Order ID
+    coid:
+      type: string
+      description: Client order ID
+      minLength: 32
+      maxLength: 32
+      pattern: ^[0-9a-f]{32}$
+      example: 550e8400e29b41d4a716446655440000
+    iid:
+      type: integer
+      description: Instrument ID
+      example: 1
+    start_timestamp:
+      type: integer
+      description: Start timestamp in milliseconds
+      example: 1767225600000
+    end_timestamp:
+      type: integer
+      description: End timestamp in milliseconds
+      example: 1767229200000
+    OrderData:
+      type: object
+      required:
+        - order_id
+        - instrument_id
+        - buy
+        - price
+        - quantity
+        - tif
+        - post_only
+        - ro
+        - status
+        - resting_quantity
+        - filled_quantity
+        - created_timestamp
+        - updated_timestamp
+      properties:
+        order_id:
+          $ref: '#/components/schemas/oid'
+        instrument_id:
+          $ref: '#/components/schemas/iid'
+        buy:
+          $ref: '#/components/schemas/buy'
+        price:
+          $ref: '#/components/schemas/p'
+        quantity:
+          $ref: '#/components/schemas/qty'
+        tif:
+          $ref: '#/components/schemas/tif'
+        post_only:
+          $ref: '#/components/schemas/po'
+        ro:
+          $ref: '#/components/schemas/ro'
+        resting_quantity:
+          $ref: '#/components/schemas/rest'
+        filled_quantity:
+          $ref: '#/components/schemas/fill'
+        status:
+          $ref: '#/components/schemas/st'
+        created_timestamp:
+          $ref: '#/components/schemas/cts'
+        updated_timestamp:
+          $ref: '#/components/schemas/uts'
+        client_order_id:
+          $ref: '#/components/schemas/coid'
+        tpsl:
+          $ref: '#/components/schemas/TpSlOrderFields'
+          description: >-
+            Conditional-order fields. Present only when the order is a TP/SL
+            conditional order — `null`/omitted for regular orders.
+    oid:
+      type: integer
+      description: Order ID
+      example: 1234567890
+    buy:
+      type: boolean
+      description: Is buy
+      example: true
+    p:
+      type: string
+      description: Price
+      example: '100.00'
+    qty:
+      type: string
+      description: Quantity in no. of contracts
+      example: '10.00'
+    tif:
+      type: string
+      description: Time in force
+      enum:
+        - gtc
+        - ioc
+        - fok
+    po:
+      type: boolean
+      description: Post only
+      default: false
+      example: false
+    ro:
+      type: boolean
+      description: Reduce only
+      example: false
+      default: false
+    rest:
+      type: string
+      description: Resting quantity
+      example: '9.00'
+    fill:
+      type: string
+      description: Filled quantity
+      example: '1.00'
+    st:
+      type: string
+      description: Order status
+      example: open
+    cts:
+      type: integer
+      description: Create timestamp in milliseconds
+      example: 1767225600000
+    uts:
+      type: integer
+      description: Update timestamp in milliseconds
+      example: 1767225600000
+    TpSlOrderFields:
+      type: object
+      description: TP/SL-specific fields surfaced alongside the regular order shape.
+      required:
+        - kind
+        - scope
+        - trp
+      properties:
+        kind:
+          $ref: '#/components/schemas/kind'
+        scope:
+          $ref: '#/components/schemas/tr_scope'
+        trp:
+          $ref: '#/components/schemas/trp'
+        parent_oid:
+          $ref: '#/components/schemas/parent_oid'
+        armed_qty:
+          $ref: '#/components/schemas/qty'
+          description: >-
+            Quantity armed at attach time (OCO) or `"0"` for position-based
+            (sized at trigger time).
+        slip_bps:
+          $ref: '#/components/schemas/slip_bps'
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    kind:
+      type: string
+      description: Conditional order type (TakeProfit / StopLoss)
+      enum:
+        - tp
+        - sl
+    tr_scope:
+      type: string
+      description: >
+        How the conditional order sizes itself.
+
+        - `order` - child of a parent entry (bracket / OCO ladder). Quantity is
+        required.
+
+        - `position` - attached to an open position. v1 always closes the full
+        position (`qty` must be `"0"`).
+      enum:
+        - order
+        - position
+    trp:
+      type: string
+      description: Trigger price
+      example: '110.00'
+    parent_oid:
+      type: integer
+      description: >-
+        Parent entry order id. Optional — omit it (do not send `0`) when the
+        parent is created in the same request (inline `CreateOrder.tpsl` or
+        `CreateTpSlArgs.parent`); the gateway auto-wires the child to it. Set it
+        only to attach an order-scoped leg to an existing resting order. Inline
+        `CreateOrder.tpsl` rejects a non-zero value; position-scoped legs carry
+        no parent.
+      example: 1234567890
+    slip_bps:
+      type: integer
+      minimum: 0
+      maximum: 10000
+      description: >-
+        Per-order market-trigger slippage cap in basis points. 0 = use the
+        per-instrument default. Clamped to the instrument cap.
+      example: 1000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-pnl.md

@@ -0,0 +1,248 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get PnL
+
+> Get PnL history for the authenticated account.
+If no end time is provided, the current time will be used.
+Maximum of 1000 entries returned per request.
+
+
+<Badge color="gray" size="md">Request Weight: **10**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/pnl
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/pnl:
+    get:
+      summary: Get PnL
+      description: |
+        Get PnL history for the authenticated account.
+        If no end time is provided, the current time will be used.
+        Maximum of 1000 entries returned per request.
+      operationId: getPnlHistory
+      parameters:
+        - name: interval
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/pnl_interval'
+        - name: start_timestamp
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/start_timestamp'
+        - name: end_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/end_timestamp'
+      responses:
+        '200':
+          description: PnL history response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PnlHistory'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    pnl_interval:
+      type: string
+      description: PnL interval
+      enum:
+        - 1h
+        - 4h
+        - 1d
+        - 1w
+    start_timestamp:
+      type: integer
+      description: Start timestamp in milliseconds
+      example: 1767225600000
+    end_timestamp:
+      type: integer
+      description: End timestamp in milliseconds
+      example: 1767229200000
+    PnlHistory:
+      type: object
+      required:
+        - data
+        - more
+      properties:
+        data:
+          type: array
+          description: |
+            - `1767225600000` - Timestamp
+            - `"100.50"` - PnL
+          items:
+            type: array
+            example:
+              - 1767225600000
+              - '100.50'
+          maxItems: 1000
+        more:
+          $ref: '#/components/schemas/more'
+    more:
+      type: boolean
+      description: More data available
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-portfolio.md

@@ -0,0 +1,350 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Portfolio
+
+> Get current portfolio snapshot including open positions, margin summary, and withdrawable balance.
+
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/portfolio
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/portfolio:
+    get:
+      summary: Get Portfolio
+      description: >
+        Get current portfolio snapshot including open positions, margin summary,
+        and withdrawable balance.
+      operationId: getPortfolio
+      responses:
+        '200':
+          description: Portfolio response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Portfolio'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    Portfolio:
+      type: object
+      required:
+        - positions
+        - margin
+        - withdrawable
+        - in_liquidation
+        - timestamp
+      properties:
+        positions:
+          type: array
+          items:
+            $ref: '#/components/schemas/PortfolioPosition'
+        margin:
+          $ref: '#/components/schemas/MarginSummary'
+        withdrawable:
+          $ref: '#/components/schemas/withdrawable'
+        in_liquidation:
+          $ref: '#/components/schemas/in_liquidation'
+        timestamp:
+          $ref: '#/components/schemas/update_timestamp'
+    PortfolioPosition:
+      type: object
+      required:
+        - instrument_id
+        - symbol
+        - size
+        - entry_price
+        - leverage
+        - cross
+        - initial_margin
+        - maintenance_margin
+        - position_value
+        - liquidation_price
+        - unrealized_pnl
+        - return_on_equity
+        - cumulative_funding
+      properties:
+        instrument_id:
+          $ref: '#/components/schemas/instrument_id'
+        symbol:
+          $ref: '#/components/schemas/symbol'
+        size:
+          $ref: '#/components/schemas/size'
+        entry_price:
+          $ref: '#/components/schemas/entry_price'
+        leverage:
+          $ref: '#/components/schemas/leverage'
+        cross:
+          $ref: '#/components/schemas/cross'
+        initial_margin:
+          $ref: '#/components/schemas/initial_margin'
+        maintenance_margin:
+          $ref: '#/components/schemas/maintenance_margin_amount'
+        position_value:
+          $ref: '#/components/schemas/position_value'
+        liquidation_price:
+          $ref: '#/components/schemas/liquidation_price'
+        unrealized_pnl:
+          $ref: '#/components/schemas/unrealized_pnl'
+        return_on_equity:
+          $ref: '#/components/schemas/return_on_equity'
+        cumulative_funding:
+          $ref: '#/components/schemas/cumulative_funding'
+    MarginSummary:
+      type: object
+      required:
+        - total_account_value
+        - total_initial_margin
+        - total_maintenance_margin
+        - total_position_value
+      properties:
+        total_account_value:
+          $ref: '#/components/schemas/total_account_value'
+        total_initial_margin:
+          $ref: '#/components/schemas/total_initial_margin'
+        total_maintenance_margin:
+          $ref: '#/components/schemas/total_maintenance_margin'
+        total_position_value:
+          $ref: '#/components/schemas/total_position_value'
+    withdrawable:
+      type: string
+      description: Withdrawable balance in USD
+      example: '13104.51'
+    in_liquidation:
+      type: boolean
+      description: Whether the account is currently under liquidation
+    update_timestamp:
+      type: integer
+      description: Update timestamp in milliseconds
+      example: 1767225600000
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    instrument_id:
+      type: integer
+      description: Instrument ID
+    symbol:
+      type: string
+      description: Instrument symbol
+      example: NVDA-USDC
+    size:
+      type: string
+      description: >-
+        Signed position size in no. of contracts (positive = long, negative =
+        short)
+      example: '10.00'
+    entry_price:
+      type: string
+      description: Average entry price
+      example: '2986.30'
+    leverage:
+      type: integer
+      description: Leverage
+      example: 10
+    cross:
+      type: boolean
+      description: Whether to use cross margin mode
+    initial_margin:
+      type: string
+      description: Initial margin in USD
+      example: '10.00'
+    maintenance_margin_amount:
+      type: string
+      description: Maintenance margin amount
+      example: '100.00'
+    position_value:
+      type: string
+      description: Notional position value in USD
+      example: '100.03'
+    liquidation_price:
+      type: string
+      description: Liquidation price
+      example: '2866.27'
+    unrealized_pnl:
+      type: string
+      description: Unrealized PnL in USD
+      example: '-0.01'
+    return_on_equity:
+      type: string
+      description: Return on equity as a decimal
+      example: '-0.0027'
+    cumulative_funding:
+      type: string
+      description: Cumulative funding paid/received in USD
+      example: '514.09'
+    total_account_value:
+      type: string
+      description: Total account value in USD (equity + unrealized PnL)
+      example: '13109.48'
+    total_initial_margin:
+      type: string
+      description: Total initial margin in use across all positions
+      example: '4.97'
+    total_maintenance_margin:
+      type: string
+      description: Total maintenance margin across all positions
+      example: '2.49'
+    total_position_value:
+      type: string
+      description: Total notional position value in USD
+      example: '100.03'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/get-public-portfolio.md

@@ -0,0 +1,232 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Public Portfolio
+
+> Get public portfolio for an address including equity and open positions.
+
+
+<Badge color="gray" size="md">Request Weight: **5**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/portfolio
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/portfolio:
+    get:
+      summary: Get Public Portfolio
+      description: |
+        Get public portfolio for an address including equity and open positions.
+      operationId: getPublicPortfolio
+      parameters:
+        - name: address
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/address'
+      responses:
+        '200':
+          description: Public portfolio response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PublicPortfolio'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    address:
+      type: string
+      description: Address
+      example: '0x1234567890abcdef1234567890abcdef12345678'
+    PublicPortfolio:
+      type: object
+      required:
+        - positions
+        - equity
+        - timestamp
+      properties:
+        positions:
+          type: array
+          items:
+            $ref: '#/components/schemas/PublicPortfolioPosition'
+        equity:
+          $ref: '#/components/schemas/equity'
+        timestamp:
+          $ref: '#/components/schemas/update_timestamp'
+    PublicPortfolioPosition:
+      type: object
+      required:
+        - instrument_id
+        - symbol
+        - size
+        - entry_price
+        - unrealized_pnl
+        - return_on_equity
+      properties:
+        instrument_id:
+          $ref: '#/components/schemas/instrument_id'
+        symbol:
+          $ref: '#/components/schemas/symbol'
+        size:
+          $ref: '#/components/schemas/size'
+        entry_price:
+          $ref: '#/components/schemas/entry_price'
+        unrealized_pnl:
+          $ref: '#/components/schemas/unrealized_pnl'
+        return_on_equity:
+          $ref: '#/components/schemas/return_on_equity'
+    equity:
+      type: string
+      description: Equity in USD
+      example: '10000.00'
+    update_timestamp:
+      type: integer
+      description: Update timestamp in milliseconds
+      example: 1767225600000
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    instrument_id:
+      type: integer
+      description: Instrument ID
+    symbol:
+      type: string
+      description: Instrument symbol
+      example: NVDA-USDC
+    size:
+      type: string
+      description: >-
+        Signed position size in no. of contracts (positive = long, negative =
+        short)
+      example: '10.00'
+    entry_price:
+      type: string
+      description: Average entry price
+      example: '2986.30'
+    unrealized_pnl:
+      type: string
+      description: Unrealized PnL in USD
+      example: '-0.01'
+    return_on_equity:
+      type: string
+      description: Return on equity as a decimal
+      example: '-0.0027'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-recent-trades.md

@@ -0,0 +1,256 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Recent Trades
+
+> Get public trades for an instrument.
+Maximum of 100 entries returned per request.
+
+
+<Badge color="gray" size="md">Request Weight: **10**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/trades
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/trades:
+    get:
+      summary: Get Recent Trades
+      description: |
+        Get public trades for an instrument.
+        Maximum of 100 entries returned per request.
+      operationId: getTrades
+      parameters:
+        - name: instrument_id
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/instrument_id'
+        - name: start_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/start_timestamp'
+        - name: end_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/end_timestamp'
+      responses:
+        '200':
+          description: Trades response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Trades'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    instrument_id:
+      type: integer
+      description: Instrument ID
+    start_timestamp:
+      type: integer
+      description: Start timestamp in milliseconds
+      example: 1767225600000
+    end_timestamp:
+      type: integer
+      description: End timestamp in milliseconds
+      example: 1767229200000
+    Trades:
+      type: object
+      required:
+        - data
+        - more
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/TradeData'
+          description: Public trades for the instrument
+        more:
+          $ref: '#/components/schemas/more'
+    TradeData:
+      type: object
+      required:
+        - trade_id
+        - instrument_id
+        - side
+        - price
+        - quantity
+        - timestamp
+        - hash
+      properties:
+        trade_id:
+          $ref: '#/components/schemas/tid'
+        instrument_id:
+          $ref: '#/components/schemas/iid'
+        side:
+          $ref: '#/components/schemas/side'
+        price:
+          $ref: '#/components/schemas/p'
+        quantity:
+          $ref: '#/components/schemas/qty'
+        timestamp:
+          $ref: '#/components/schemas/ts'
+        hash:
+          $ref: '#/components/schemas/hash'
+    more:
+      type: boolean
+      description: More data available
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    tid:
+      type: integer
+      description: Trade ID
+      example: 1
+    iid:
+      type: integer
+      description: Instrument ID
+      example: 1
+    side:
+      type: string
+      description: Side
+      enum:
+        - long
+        - short
+    p:
+      type: string
+      description: Price
+      example: '100.00'
+    qty:
+      type: string
+      description: Quantity in no. of contracts
+      example: '10.00'
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+    hash:
+      type: string
+      description: On-chain transaction hash, "0x" if not yet mined
+      default: 0x
+      example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-server-time.md

@@ -0,0 +1,139 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Server Time
+
+> Get server time.
+
+
+<Badge color="gray" size="md">Request Weight: **1**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/time
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/time:
+    get:
+      summary: Get Server Time
+      description: |
+        Get server time.
+      operationId: getTime
+      responses:
+        '200':
+          description: Successful time response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Time'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    Time:
+      type: object
+      required:
+        - time
+      properties:
+        time:
+          $ref: '#/components/schemas/time'
+    time:
+      type: integer
+      description: Timestamp in milliseconds
+      example: 1767225600000
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-statistics.md

@@ -0,0 +1,195 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Statistics
+
+> Get last 24-hour statistics for all instruments.
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/statistics
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/statistics:
+    get:
+      summary: Get Statistics
+      description: Get last 24-hour statistics for all instruments.
+      operationId: getStatistics
+      parameters:
+        - name: instrument_id
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/instrument_id'
+      responses:
+        '200':
+          description: Statistics response.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Statistic'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    instrument_id:
+      type: integer
+      description: Instrument ID
+    Statistic:
+      type: object
+      required:
+        - instrument_id
+        - symbol
+        - volume
+        - open_price
+        - klines
+      properties:
+        instrument_id:
+          $ref: '#/components/schemas/iid'
+        symbol:
+          $ref: '#/components/schemas/symbol'
+        volume:
+          $ref: '#/components/schemas/volume'
+        open_price:
+          $ref: '#/components/schemas/open_price'
+        klines:
+          $ref: '#/components/schemas/klines'
+    iid:
+      type: integer
+      description: Instrument ID
+      example: 1
+    symbol:
+      type: string
+      description: Instrument symbol
+      example: NVDA-USDC
+    volume:
+      type: string
+      description: 24-hour trading volume in contracts
+      example: '1000.00'
+    open_price:
+      type: string
+      description: Opening price from 24 hours ago
+      example: '100.50'
+    klines:
+      type: array
+      items:
+        $ref: '#/components/schemas/kline'
+      description: Last 24-hour kline data
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    kline:
+      type: array
+      description: |
+        - `1767225600000` - Open time
+        - `"100.00"` - Open price
+        - `"105.00"` - High price
+        - `"99.00"` - Low price
+        - `"102.00"` - Close price
+        - `"500.00"` - Volume (base unit)
+        - `42` - Number of trades
+      example:
+        - 1767225600000
+        - '100.00'
+        - '105.00'
+        - '99.00'
+        - '102.00'
+        - '500.00'
+        - 42
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-tickers.md

@@ -0,0 +1,213 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Tickers
+
+> Get all instrument tickers with live market data.
+
+<Badge color="gray" size="md">Request Weight: **2**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/tickers
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/tickers:
+    get:
+      summary: Get Tickers
+      description: Get all instrument tickers with live market data.
+      operationId: getTickers
+      parameters:
+        - name: instrument_id
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/instrument_id'
+      responses:
+        '200':
+          description: Tickers response.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Ticker'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    instrument_id:
+      type: integer
+      description: Instrument ID
+    Ticker:
+      allOf:
+        - $ref: '#/components/schemas/TickerData'
+        - type: object
+          required:
+            - timestamp
+          properties:
+            timestamp:
+              $ref: '#/components/schemas/timestamp'
+    TickerData:
+      type: object
+      required:
+        - instrument_id
+        - symbol
+        - index_price
+        - mark_price
+        - last_price
+        - mid_price
+        - open_interest
+        - funding_rate
+        - next_funding
+      properties:
+        instrument_id:
+          $ref: '#/components/schemas/instrument_id'
+        symbol:
+          $ref: '#/components/schemas/symbol'
+        index_price:
+          $ref: '#/components/schemas/index_price'
+        mark_price:
+          $ref: '#/components/schemas/mark_price'
+        last_price:
+          $ref: '#/components/schemas/last_price'
+        mid_price:
+          $ref: '#/components/schemas/mid_price'
+        open_interest:
+          $ref: '#/components/schemas/open_interest'
+        funding_rate:
+          $ref: '#/components/schemas/funding_rate'
+        next_funding:
+          $ref: '#/components/schemas/next_funding'
+    timestamp:
+      type: integer
+      description: Timestamp in milliseconds
+      example: 1767225600000
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    symbol:
+      type: string
+      description: Instrument symbol
+      example: NVDA-USDC
+    index_price:
+      type: string
+      description: Index price
+      example: '100.00'
+    mark_price:
+      type: string
+      description: Mark price
+      example: '100.00'
+    last_price:
+      type: string
+      description: Last traded price
+      example: '100.00'
+    mid_price:
+      type: string
+      description: Mid price
+      example: '100.00'
+    open_interest:
+      type: string
+      description: Open interest in number of contracts
+      example: '10.00'
+    funding_rate:
+      type: string
+      description: Funding rate
+      example: '0.0001'
+    next_funding:
+      type: integer
+      description: Next funding timestamp in milliseconds
+      example: 1767225600000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/get-withdrawals.md

@@ -0,0 +1,325 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Get Withdrawals
+
+> Get withdrawal history for the authenticated account.
+If no end time is provided, the current time will be used.
+Maximum of 100 entries returned per request.
+
+
+<Badge color="gray" size="md">Request Weight: **10**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/account/withdrawals
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/withdrawals:
+    get:
+      summary: Get Withdrawals
+      description: |
+        Get withdrawal history for the authenticated account.
+        If no end time is provided, the current time will be used.
+        Maximum of 100 entries returned per request.
+      operationId: getWithdrawals
+      parameters:
+        - name: withdrawal_status
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/withdrawal_status'
+        - name: hash
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/hash'
+        - name: start_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/start_timestamp'
+        - name: end_timestamp
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/end_timestamp'
+      responses:
+        '200':
+          description: Withdrawal history response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Withdrawals'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '401':
+          $ref: '#/components/responses/Error401Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security:
+        - polymarket_proxy: []
+          polymarket_secret: []
+components:
+  schemas:
+    withdrawal_status:
+      type: string
+      description: Withdrawal status
+      enum:
+        - pending
+        - confirmed
+        - removed
+        - failed
+    hash:
+      type: string
+      description: On-chain transaction hash, "0x" if not yet mined
+      default: 0x
+      example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+    start_timestamp:
+      type: integer
+      description: Start timestamp in milliseconds
+      example: 1767225600000
+    end_timestamp:
+      type: integer
+      description: End timestamp in milliseconds
+      example: 1767229200000
+    Withdrawals:
+      type: object
+      required:
+        - data
+        - more
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/Withdrawal'
+        more:
+          $ref: '#/components/schemas/more'
+    Withdrawal:
+      type: object
+      required:
+        - withdraw_id
+        - asset
+        - amount
+        - fee
+        - status
+        - to
+        - hash
+        - confirmations
+        - required_confirmations
+        - created_timestamp
+      properties:
+        withdraw_id:
+          $ref: '#/components/schemas/withdraw_id'
+        asset:
+          $ref: '#/components/schemas/asset'
+        amount:
+          $ref: '#/components/schemas/amount'
+        to:
+          $ref: '#/components/schemas/to'
+        fee:
+          $ref: '#/components/schemas/withdrawal_fee'
+        status:
+          $ref: '#/components/schemas/withdrawal_status'
+        hash:
+          $ref: '#/components/schemas/hash'
+        confirmations:
+          $ref: '#/components/schemas/confirmations'
+        required_confirmations:
+          $ref: '#/components/schemas/required_confirmations'
+        created_timestamp:
+          $ref: '#/components/schemas/created_timestamp'
+        confirmed_timestamp:
+          $ref: '#/components/schemas/confirmed_timestamp'
+    more:
+      type: boolean
+      description: More data available
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error401:
+      title: Error401
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    withdraw_id:
+      type: integer
+      description: Withdraw ID
+    asset:
+      type: string
+      description: Asset name
+      example: USDC
+    amount:
+      type: string
+      description: >-
+        Raw token amount including decimals. For withdrawals this matches the
+        uint256 amount in the EIP-712 signature (e.g. "100000000" for 100 USDC
+        with 6 decimals).
+      example: '100000000'
+    to:
+      type: string
+      description: Destination address in hex format
+      example: '0x1234567890abcdef1234567890abcdef12345678'
+    withdrawal_fee:
+      type: string
+      description: Withdrawal transaction fee in decimalized asset units
+      example: '5.00'
+    confirmations:
+      type: integer
+      description: Number of block confirmations
+      example: 12
+    required_confirmations:
+      type: integer
+      description: Required number of block confirmations
+      example: 12
+    created_timestamp:
+      type: integer
+      description: Creation timestamp in milliseconds
+      example: 1767225600000
+    confirmed_timestamp:
+      type: integer
+      description: Confirmation timestamp in milliseconds
+      example: 1767225600000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error401Response:
+      description: >
+        Unauthorized — missing or invalid `POLYMARKET-PROXY` /
+        `POLYMARKET-SECRET`
+
+        credentials. `error` is `unauthorized`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error401'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  securitySchemes:
+    polymarket_proxy:
+      type: apiKey
+      name: POLYMARKET-PROXY
+      in: header
+      description: Proxy address
+    polymarket_secret:
+      type: apiKey
+      name: POLYMARKET-SECRET
+      in: header
+      description: Correponding proxy secret
+
+````

docs/api-reference/internal-transfer.md

@@ -0,0 +1,304 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Internal Transfer
+
+> Submit a signed internal ledger transfer between two exchange accounts.
+Requires proxy signature using the standard signed-op flow.
+
+
+<Badge color="gray" size="md">Request Weight: **1**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json post /v1/account/internal-transfer
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/internal-transfer:
+    post:
+      summary: Internal Transfer
+      description: |
+        Submit a signed internal ledger transfer between two exchange accounts.
+        Requires proxy signature using the standard signed-op flow.
+      operationId: internalTransfer
+      requestBody:
+        description: Internal transfer request.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/InternalTransferRequest'
+            examples:
+              transfer:
+                summary: Transfer USDC to another account
+                value:
+                  op:
+                    type: internalTransfer
+                    args:
+                      account: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
+                      token: '0xaf88d065e77c8cc2239327c5edb3a432268e5831'
+                      amount: '100.00'
+                      to: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'
+                  sig: >-
+                    0x5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a1c
+                  salt: 555555555
+                  ts: 1767000014000
+                  label: ops-rebalance
+      responses:
+        '200':
+          description: The accepted transfer, carrying its `transfer_id`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InternalTransferAccepted'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '422':
+          description: |
+            The transfer was rejected on its merits (e.g. insufficient balance,
+            transfer to self). The body carries `transfer_id` and `error`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InternalTransferRejected'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    InternalTransferRequest:
+      allOf:
+        - type: object
+          required:
+            - op
+          properties:
+            op:
+              $ref: '#/components/schemas/OpInternalTransfer'
+        - $ref: '#/components/schemas/BaseOp'
+        - type: object
+          properties:
+            label:
+              $ref: '#/components/schemas/label'
+    InternalTransferAccepted:
+      type: object
+      required:
+        - status
+        - transfer_id
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+        transfer_id:
+          $ref: '#/components/schemas/transfer_id'
+    InternalTransferRejected:
+      type: object
+      required:
+        - status
+        - transfer_id
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        transfer_id:
+          $ref: '#/components/schemas/transfer_id'
+        error:
+          $ref: '#/components/schemas/error'
+    OpInternalTransfer:
+      type: object
+      required:
+        - type
+        - args
+      properties:
+        type:
+          type: string
+          enum:
+            - internalTransfer
+        args:
+          type: object
+          required:
+            - account
+            - token
+            - amount
+            - to
+          properties:
+            account:
+              $ref: '#/components/schemas/account'
+            token:
+              $ref: '#/components/schemas/token'
+            amount:
+              $ref: '#/components/schemas/amount'
+            to:
+              $ref: '#/components/schemas/to'
+    BaseOp:
+      type: object
+      required:
+        - sig
+        - salt
+        - ts
+      properties:
+        sig:
+          $ref: '#/components/schemas/sig'
+        salt:
+          $ref: '#/components/schemas/salt'
+        ts:
+          $ref: '#/components/schemas/ts'
+    label:
+      type: string
+      description: Human-readable label for a proxy key or internal transfer
+      example: trading-bot
+    transfer_id:
+      type: integer
+      description: Internal transfer ID
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    account:
+      type: string
+      description: Account address in hex format
+      example: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
+    token:
+      type: string
+      description: Token contract address in hex format
+      example: '0xaf88d065e77c8cc2239327c5edb3a432268e5831'
+    amount:
+      type: string
+      description: >-
+        Raw token amount including decimals. For withdrawals this matches the
+        uint256 amount in the EIP-712 signature (e.g. "100000000" for 100 USDC
+        with 6 decimals).
+      example: '100000000'
+    to:
+      type: string
+      description: Destination address in hex format
+      example: '0x1234567890abcdef1234567890abcdef12345678'
+    sig:
+      type: string
+      description: Signature in hex format
+      example: 0x1234567890...
+    salt:
+      type: integer
+      description: Salt
+      example: 1234567890
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/set-auto-cancel.md

@@ -0,0 +1,364 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Set Auto-Cancel
+
+> Set a dead man switch that will cancel all open orders at the specified time.
+Time must be at least 5 seconds in the future, or `0` to clear an active
+schedule without triggering it. Posting a new auto-cancel replaces the
+previous one.
+
+The switch is one-shot: once the deadline elapses and your open orders are
+cancelled, the schedule clears automatically. Orders you place after the
+fire are not affected by the expired deadline — re-arm to extend
+protection.
+
+Each account may trigger auto-cancel at most 10 times per UTC day. Once
+that limit is reached, further attempts to arm a schedule are rejected with
+`auto_cancel_daily_limit_reached` until the next UTC day; clearing an
+existing schedule (`time: 0`) is always allowed.
+
+Use `GET /v1/account/auto-cancel` to check the current deadline, today's
+trigger count, and when the daily counter resets.
+
+Requires proxy signature, see [proxy signing](/http/signing#2-proxy-signing).
+
+
+<Badge color="gray" size="md">Request Weight: **1**</Badge> <Badge color="gray" size="md">Action Weight: **10**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json patch /v1/trade/auto-cancel
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/trade/auto-cancel:
+    patch:
+      summary: Set Auto-Cancel
+      description: >
+        Set a dead man switch that will cancel all open orders at the specified
+        time.
+
+        Time must be at least 5 seconds in the future, or `0` to clear an active
+
+        schedule without triggering it. Posting a new auto-cancel replaces the
+
+        previous one.
+
+
+        The switch is one-shot: once the deadline elapses and your open orders
+        are
+
+        cancelled, the schedule clears automatically. Orders you place after the
+
+        fire are not affected by the expired deadline — re-arm to extend
+
+        protection.
+
+
+        Each account may trigger auto-cancel at most 10 times per UTC day. Once
+
+        that limit is reached, further attempts to arm a schedule are rejected
+        with
+
+        `auto_cancel_daily_limit_reached` until the next UTC day; clearing an
+
+        existing schedule (`time: 0`) is always allowed.
+
+
+        Use `GET /v1/account/auto-cancel` to check the current deadline, today's
+
+        trigger count, and when the daily counter resets.
+
+
+        Requires proxy signature, see [proxy
+        signing](/http/signing#2-proxy-signing).
+      operationId: setAutoCancel
+      requestBody:
+        description: Auto-cancel request.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AutoCancelRequest'
+            examples:
+              enable:
+                summary: Enable auto-cancel
+                value:
+                  op:
+                    type: autoCancel
+                    args:
+                      time: 1767000045000
+                  sig: >-
+                    0x2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b1c
+                  salt: 666666666
+                  ts: 1767000015000
+              disable:
+                summary: Disable auto-cancel
+                value:
+                  op:
+                    type: autoCancel
+                    args:
+                      time: 0
+                  sig: >-
+                    0x8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f1c
+                  salt: 666666667
+                  ts: 1767000016000
+      responses:
+        '200':
+          description: The effective auto-cancel schedule after the update.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AutoCancelResponse'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '404':
+          $ref: '#/components/responses/Error404Response'
+        '422':
+          $ref: '#/components/responses/Error422Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    AutoCancelRequest:
+      allOf:
+        - type: object
+          required:
+            - op
+          properties:
+            op:
+              $ref: '#/components/schemas/OpAutoCancel'
+        - $ref: '#/components/schemas/BaseOp'
+    AutoCancelResponse:
+      description: >
+        The effective auto-cancel schedule after the update. `deadline` echoes
+        the
+
+        armed Unix-ms time, or `0` when the schedule was cleared (`time: 0`).
+      type: object
+      required:
+        - status
+        - deadline
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+        deadline:
+          $ref: '#/components/schemas/auto_cancel_deadline'
+    OpAutoCancel:
+      type: object
+      required:
+        - type
+        - args
+      properties:
+        type:
+          type: string
+          enum:
+            - autoCancel
+        args:
+          type: object
+          required:
+            - time
+          properties:
+            time:
+              $ref: '#/components/schemas/time'
+    BaseOp:
+      type: object
+      required:
+        - sig
+        - salt
+        - ts
+      properties:
+        sig:
+          $ref: '#/components/schemas/sig'
+        salt:
+          $ref: '#/components/schemas/salt'
+        ts:
+          $ref: '#/components/schemas/ts'
+    auto_cancel_deadline:
+      type: integer
+      description: |
+        Unix-ms deadline for the per-account auto-cancel dead-man-switch.
+        Zero means no schedule is armed. When the deadline elapses, every
+        open order on the account is cancelled and the schedule clears.
+      example: 1767000045000
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error404:
+      title: Error404
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    GenericRejected:
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    time:
+      type: integer
+      description: Timestamp in milliseconds
+      example: 1767225600000
+    sig:
+      type: string
+      description: Signature in hex format
+      example: 0x1234567890...
+    salt:
+      type: integer
+      description: Salt
+      example: 1234567890
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error404Response:
+      description: |
+        Not found — the endpoint is disabled on this venue (e.g. auto-cancel) or
+        the route does not exist. `error` is `not_found`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error404'
+    Error422Response:
+      description: |
+        Unprocessable Entity — the request was well-formed but a domain rule
+        rejected it on its merits (insufficient balance, invalid leverage,
+        proxy already exists, …). The body is the discriminated rejection
+        (`status: err`) with the engine error identifier in `error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/GenericRejected'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/test-connection.md

@@ -0,0 +1,134 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Test Connection
+
+> Test connection to the server.
+
+
+<Badge color="gray" size="md">Request Weight: **1**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json get /v1/info/ping
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/info/ping:
+    get:
+      summary: Test Connection
+      description: |
+        Test connection to the server.
+      operationId: getPing
+      responses:
+        '200':
+          description: Successful ping response.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - status
+                properties:
+                  status:
+                    type: string
+                    example: ok
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  responses:
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+  schemas:
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+
+````

docs/api-reference/update-leverage.md

@@ -0,0 +1,290 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Update Leverage
+
+> Update leverage for an instrument.
+Requires proxy signature, see [proxy signing](/http/signing#2-proxy-signing).
+
+
+<Badge color="gray" size="md">Request Weight: **1**</Badge> <Badge color="gray" size="md">Action Weight: **1**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json patch /v1/trade/leverage
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/trade/leverage:
+    patch:
+      summary: Update Leverage
+      description: >
+        Update leverage for an instrument.
+
+        Requires proxy signature, see [proxy
+        signing](/http/signing#2-proxy-signing).
+      operationId: updateLeverage
+      requestBody:
+        description: Leverage request.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/LeverageRequest'
+            examples:
+              updateLeverage:
+                summary: Update leverage for one instrument
+                value:
+                  op:
+                    type: updateLeverage
+                    args:
+                      iid: 1
+                      lev: 5
+                      cross: false
+                  sig: >-
+                    0x59ed57f6dce8d15aa01e774ef53d9957c84801fb34ec655f6a2ea344af8a58843095314730a3f1bd8f0f4560f6dc6f8de69d3f2d0a6f3365fc877f7f4845d40b1c
+                  salt: 333333333
+                  ts: 1767000012000
+      responses:
+        '200':
+          description: The instrument's effective leverage configuration after the update.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LeverageResponse'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '422':
+          $ref: '#/components/responses/Error422Response'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    LeverageRequest:
+      allOf:
+        - type: object
+          required:
+            - op
+          properties:
+            op:
+              $ref: '#/components/schemas/OpUpdateLeverage'
+        - $ref: '#/components/schemas/BaseOp'
+    LeverageResponse:
+      description: The instrument's effective leverage configuration after the update.
+      type: object
+      required:
+        - status
+        - instrument_id
+        - leverage
+        - cross
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+        instrument_id:
+          $ref: '#/components/schemas/iid'
+        leverage:
+          $ref: '#/components/schemas/lev'
+        cross:
+          $ref: '#/components/schemas/cross'
+    OpUpdateLeverage:
+      type: object
+      required:
+        - type
+        - args
+      properties:
+        type:
+          type: string
+          enum:
+            - updateLeverage
+        args:
+          type: object
+          required:
+            - iid
+            - lev
+            - cross
+          properties:
+            iid:
+              $ref: '#/components/schemas/iid'
+            lev:
+              $ref: '#/components/schemas/lev'
+            cross:
+              $ref: '#/components/schemas/cross'
+    BaseOp:
+      type: object
+      required:
+        - sig
+        - salt
+        - ts
+      properties:
+        sig:
+          $ref: '#/components/schemas/sig'
+        salt:
+          $ref: '#/components/schemas/salt'
+        ts:
+          $ref: '#/components/schemas/ts'
+    iid:
+      type: integer
+      description: Instrument ID
+      example: 1
+    lev:
+      type: integer
+      description: Leverage
+      example: 10
+    cross:
+      type: boolean
+      description: Whether to use cross margin mode
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    GenericRejected:
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    sig:
+      type: string
+      description: Signature in hex format
+      example: 0x1234567890...
+    salt:
+      type: integer
+      description: Salt
+      example: 1234567890
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error422Response:
+      description: |
+        Unprocessable Entity — the request was well-formed but a domain rule
+        rejected it on its merits (insufficient balance, invalid leverage,
+        proxy already exists, …). The body is the discriminated rejection
+        (`status: err`) with the engine error identifier in `error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/GenericRejected'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/withdraw.md

@@ -0,0 +1,318 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Withdraw
+
+> Submit a signed withdrawal request.
+Requires EOA signature, see [EOA signing](/http/signing#1-eoa-signing).
+
+The `amount` field is the raw token amount including decimals (e.g. `"100000000"` for 100 USDC).
+This must match the `uint256 amount` value used in the EIP-712 `Withdraw` signature.
+
+The `ts` field is Unix seconds (not milliseconds) because the on-chain contract validates it
+against `block.timestamp`. It must also match the `uint64 ts` in the signed EIP-712 struct.
+
+
+<Badge color="gray" size="md">Request Weight: **1**</Badge>
+
+
+## OpenAPI
+
+````yaml /api-spec/perps-openapi.json post /v1/account/withdraw
+openapi: 3.0.3
+info:
+  title: Polymarket Perps HTTP API
+  version: 1.0.0
+  description: HTTP API for Polymarket perpetual trading system.
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+  - url: https://api.perpetuals.polymarket.com
+    description: Production Perps HTTP API
+security: []
+paths:
+  /v1/account/withdraw:
+    post:
+      summary: Withdraw
+      description: >
+        Submit a signed withdrawal request.
+
+        Requires EOA signature, see [EOA signing](/http/signing#1-eoa-signing).
+
+
+        The `amount` field is the raw token amount including decimals (e.g.
+        `"100000000"` for 100 USDC).
+
+        This must match the `uint256 amount` value used in the EIP-712
+        `Withdraw` signature.
+
+
+        The `ts` field is Unix seconds (not milliseconds) because the on-chain
+        contract validates it
+
+        against `block.timestamp`. It must also match the `uint64 ts` in the
+        signed EIP-712 struct.
+      operationId: withdraw
+      requestBody:
+        description: Withdraw request.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WithdrawRequest'
+            examples:
+              withdraw:
+                summary: Withdraw 100 USDC
+                value:
+                  op:
+                    type: withdraw
+                    args:
+                      account: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
+                      token: '0xaf88d065e77c8cc2239327c5edb3a432268e5831'
+                      amount: '100000000'
+                      to: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'
+                  sig: >-
+                    0x5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a1c
+                  salt: 555555555
+                  ts: 1767000014
+      responses:
+        '200':
+          description: The accepted withdrawal, carrying its `withdraw_id`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WithdrawAccepted'
+        '400':
+          $ref: '#/components/responses/Error400Response'
+        '422':
+          description: >
+            The withdrawal was rejected on its merits (e.g. insufficient
+            balance).
+
+            The body carries `withdraw_id` and `error`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WithdrawRejected'
+        '429':
+          $ref: '#/components/responses/Error429Response'
+        '500':
+          $ref: '#/components/responses/Error500Response'
+      security: []
+components:
+  schemas:
+    WithdrawRequest:
+      allOf:
+        - type: object
+          required:
+            - op
+          properties:
+            op:
+              $ref: '#/components/schemas/OpWithdraw'
+        - $ref: '#/components/schemas/BaseOp'
+    WithdrawAccepted:
+      type: object
+      required:
+        - status
+        - withdraw_id
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+        withdraw_id:
+          $ref: '#/components/schemas/withdraw_id'
+    WithdrawRejected:
+      type: object
+      required:
+        - status
+        - withdraw_id
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        withdraw_id:
+          $ref: '#/components/schemas/withdraw_id'
+        error:
+          $ref: '#/components/schemas/error'
+    OpWithdraw:
+      type: object
+      required:
+        - type
+        - args
+      properties:
+        type:
+          type: string
+          enum:
+            - withdraw
+        args:
+          type: object
+          required:
+            - account
+            - token
+            - amount
+            - to
+          properties:
+            account:
+              $ref: '#/components/schemas/account'
+            token:
+              $ref: '#/components/schemas/token'
+            amount:
+              $ref: '#/components/schemas/amount'
+            to:
+              $ref: '#/components/schemas/to'
+    BaseOp:
+      type: object
+      required:
+        - sig
+        - salt
+        - ts
+      properties:
+        sig:
+          $ref: '#/components/schemas/sig'
+        salt:
+          $ref: '#/components/schemas/salt'
+        ts:
+          $ref: '#/components/schemas/ts'
+    withdraw_id:
+      type: integer
+      description: Withdraw ID
+    Error400:
+      title: Error400
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    error:
+      type: string
+      description: >-
+        Error identifier. For domain rejections and transport errors
+        (`401`/`404`/`429`/`500`) this is a stable, machine-readable snake_case
+        identifier that is part of the API contract and safe to branch on, e.g.
+        `insufficient_margin`, `insufficient_balance`, `order_not_found`,
+        `reduce_only_invalid`, `unauthorized`, `not_found`. For `400` it is a
+        human-readable validation detail whose wording may change. See the Error
+        handling guide for the domain identifiers. (Post-only / Fill-or-Kill
+        outcomes are order statuses such as `post_only_rejected`, not
+        rejections.)
+      example: insufficient_margin
+    Error429:
+      title: Error429
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    Error500:
+      title: Error500
+      type: object
+      required:
+        - status
+        - error
+      properties:
+        status:
+          type: string
+          enum:
+            - err
+        error:
+          $ref: '#/components/schemas/error'
+    account:
+      type: string
+      description: Account address in hex format
+      example: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
+    token:
+      type: string
+      description: Token contract address in hex format
+      example: '0xaf88d065e77c8cc2239327c5edb3a432268e5831'
+    amount:
+      type: string
+      description: >-
+        Raw token amount including decimals. For withdrawals this matches the
+        uint256 amount in the EIP-712 signature (e.g. "100000000" for 100 USDC
+        with 6 decimals).
+      example: '100000000'
+    to:
+      type: string
+      description: Destination address in hex format
+      example: '0x1234567890abcdef1234567890abcdef12345678'
+    sig:
+      type: string
+      description: Signature in hex format
+      example: 0x1234567890...
+    salt:
+      type: integer
+      description: Salt
+      example: 1234567890
+    ts:
+      type: integer
+      description: >-
+        Request timestamp. Unix milliseconds for most operations; Unix seconds
+        for withdrawals (must match the on-chain EIP-712 struct verified against
+        block.timestamp).
+      example: 1767225600000
+  responses:
+    Error400Response:
+      description: |
+        Bad request — the request was malformed or failed validation (bad query
+        parameters, unparseable body, invalid signature, or a domain pre-check).
+        The `error` field is a human-readable validation detail.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error400'
+    Error429Response:
+      description: >
+        Too Many Requests. `error` distinguishes the limit that was hit:
+
+        `ip_rate_limited` (per-IP token bucket), `action_rate_limited`
+        (per-account
+
+        action rate), or `open_orders_limit` (resting open-order cap).
+      headers:
+        Retry-After:
+          description: >
+            Whole seconds to wait before retrying. Present only on token-bucket
+
+            rate-limit rejections (`ip_rate_limited` and `action_rate_limited`);
+            a
+
+            conservative estimate of when enough capacity will have refilled to
+
+            admit the request. Absent on `open_orders_limit`, which is a
+            capacity
+
+            limit, not a rate limit — waiting does not free order slots; cancel
+
+            resting orders or wait for fills instead.
+          schema:
+            type: integer
+            example: 2
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error429'
+    Error500Response:
+      description: |
+        Internal server error. `error` is `internal_error`.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error500'
+
+````

docs/api-reference/wss/perps-auth.md

@@ -0,0 +1,274 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Auth
+
+> Perps WebSocket authentication.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json auth
+id: auth
+title: Auth
+description: Authentication to access private channels.
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: AuthSend
+    title: Auth send
+    description: Authenticate connection
+    type: receive
+    messages:
+      - &ref_3
+        id: Request
+        contentType: application/json
+        payload:
+          - name: Auth
+            description: Authenticate this WebSocket connection for private channels
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: op
+                type: object
+                required: true
+                properties:
+                  - name: type
+                    type: string
+                    enumValues:
+                      - auth
+                    required: true
+                  - name: args
+                    type: object
+                    required: true
+                    properties:
+                      - name: proxy
+                        type: string
+                        description: Proxy address in hex format
+                        required: true
+                      - name: secret
+                        type: string
+                        description: API secret
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-134>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-135>
+            op:
+              type: object
+              required:
+                - type
+                - args
+              properties:
+                type:
+                  type: string
+                  enum:
+                    - auth
+                  x-parser-schema-id: <anonymous-schema-137>
+                args:
+                  type: object
+                  required:
+                    - proxy
+                    - secret
+                  properties:
+                    proxy:
+                      type: string
+                      description: Proxy address in hex format
+                      example: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'
+                      x-parser-schema-id: <anonymous-schema-139>
+                    secret:
+                      type: string
+                      description: API secret
+                      example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+                      x-parser-schema-id: <anonymous-schema-140>
+                  x-parser-schema-id: <anonymous-schema-138>
+              x-parser-schema-id: <anonymous-schema-136>
+          required:
+            - req
+            - op
+          x-parser-schema-id: <anonymous-schema-133>
+        title: Auth
+        description: Authenticate this WebSocket connection for private channels
+        example: |-
+          {
+            "req": "post",
+            "op": {
+              "type": "auth",
+              "args": {
+                "proxy": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
+                "secret": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+              }
+            }
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Request
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: auth
+  - &ref_2
+    id: AuthReceive
+    title: Auth receive
+    description: Auth response
+    type: send
+    messages:
+      - &ref_4
+        id: Response
+        contentType: application/json
+        payload:
+          - name: Auth Response
+            description: Authentication result
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: object
+                required: true
+                properties:
+                  - name: status
+                    type: string
+                    enumValues:
+                      - ok
+                    required: true
+                  - name: status
+                    type: string
+                    enumValues:
+                      - err
+                    required: true
+                  - name: error
+                    type: string
+                    description: >-
+                      Error identifier. For domain rejections and transport
+                      errors (`401`/`404`/`429`/`500`) this is a stable,
+                      machine-readable snake_case identifier that is part of the
+                      API contract and safe to branch on, e.g.
+                      `insufficient_margin`, `insufficient_balance`,
+                      `order_not_found`, `reduce_only_invalid`, `unauthorized`,
+                      `not_found`. For `400` it is a human-readable validation
+                      detail whose wording may change. See the Error handling
+                      guide for the domain identifiers. (Post-only /
+                      Fill-or-Kill outcomes are order statuses such as
+                      `post_only_rejected`, not rejections.)
+                    required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-142>
+            data:
+              oneOf:
+                - type: object
+                  required:
+                    - status
+                  properties:
+                    status:
+                      type: string
+                      enum:
+                        - ok
+                      x-parser-schema-id: <anonymous-schema-145>
+                  x-parser-schema-id: <anonymous-schema-144>
+                - type: object
+                  required:
+                    - status
+                    - error
+                  properties:
+                    status:
+                      type: string
+                      enum:
+                        - err
+                      x-parser-schema-id: <anonymous-schema-147>
+                    error:
+                      type: string
+                      description: >-
+                        Error identifier. For domain rejections and transport
+                        errors (`401`/`404`/`429`/`500`) this is a stable,
+                        machine-readable snake_case identifier that is part of
+                        the API contract and safe to branch on, e.g.
+                        `insufficient_margin`, `insufficient_balance`,
+                        `order_not_found`, `reduce_only_invalid`,
+                        `unauthorized`, `not_found`. For `400` it is a
+                        human-readable validation detail whose wording may
+                        change. See the Error handling guide for the domain
+                        identifiers. (Post-only / Fill-or-Kill outcomes are
+                        order statuses such as `post_only_rejected`, not
+                        rejections.)
+                      example: insufficient_margin
+                      x-parser-schema-id: <anonymous-schema-148>
+                  x-parser-schema-id: <anonymous-schema-146>
+              x-parser-schema-id: <anonymous-schema-143>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-141>
+        title: Auth Response
+        description: Authentication result
+        example: |-
+          {
+            "id": 123,
+            "data": {
+              "status": "<string>",
+              "error": "<string>"
+            }
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Response
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+receiveOperations:
+  - *ref_2
+sendMessages:
+  - *ref_3
+receiveMessages:
+  - *ref_4
+extensions:
+  - id: x-parser-unique-object-id
+    value: auth
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-auto-cancel.md

@@ -0,0 +1,305 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Auto Cancel
+
+> Perps WebSocket dead man's switch updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json autoCancel
+id: autoCancel
+title: Auto-Cancel
+description: |
+  Arm or clear the per-account auto-cancel schedule.
+  Requires proxy signature, see [proxy signing](/http/signing#2-proxy-signing).
+
+  <Badge color="gray" size="md">Action Weight: **10**</Badge>
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: AutoCancelSend
+    title: Auto cancel send
+    description: Set or clear auto-cancel
+    type: receive
+    messages:
+      - &ref_3
+        id: Request
+        contentType: application/json
+        payload:
+          - name: Auto-Cancel Request
+            description: Client submits a signed auto-cancel request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: op
+                type: object
+                required: true
+                properties:
+                  - name: type
+                    type: string
+                    enumValues:
+                      - autoCancel
+                    required: true
+                  - name: args
+                    type: object
+                    required: true
+                    properties:
+                      - name: time
+                        type: integer
+                        description: Timestamp in milliseconds
+                        required: true
+              - name: sig
+                type: string
+                description: Signature in hex format
+                required: true
+              - name: salt
+                type: integer
+                description: Salt
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-96>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-97>
+            op:
+              type: object
+              required:
+                - type
+                - args
+              properties:
+                type:
+                  type: string
+                  enum:
+                    - autoCancel
+                  x-parser-schema-id: <anonymous-schema-99>
+                args:
+                  type: object
+                  required:
+                    - time
+                  properties:
+                    time:
+                      type: integer
+                      description: Timestamp in milliseconds
+                      example: 1767225600000
+                      x-parser-schema-id: <anonymous-schema-101>
+                  x-parser-schema-id: <anonymous-schema-100>
+              x-parser-schema-id: <anonymous-schema-98>
+            sig:
+              type: string
+              description: Signature in hex format
+              example: 0x1234567890...
+              x-parser-schema-id: <anonymous-schema-102>
+            salt:
+              type: integer
+              description: Salt
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-103>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-104>
+          required:
+            - req
+            - op
+            - sig
+            - salt
+            - ts
+          x-parser-schema-id: <anonymous-schema-95>
+        title: Auto-Cancel Request
+        description: Client submits a signed auto-cancel request
+        example: |-
+          {
+            "req": "post",
+            "op": {
+              "type": "autoCancel",
+              "args": {
+                "time": 1767225600000
+              }
+            },
+            "sig": "0x1234567890...",
+            "salt": 1234567890,
+            "ts": 1767225600000
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Request
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: autoCancel
+  - &ref_2
+    id: AutoCancelReceive
+    title: Auto cancel receive
+    description: Auto-cancel response
+    type: send
+    messages:
+      - &ref_4
+        id: Response
+        contentType: application/json
+        payload:
+          - name: Auto-Cancel Response
+            description: Server responds with auto-cancel result
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: object
+                required: true
+                properties:
+                  - name: status
+                    type: string
+                    enumValues:
+                      - ok
+                    required: true
+                  - name: status
+                    type: string
+                    enumValues:
+                      - err
+                    required: true
+                  - name: error
+                    type: string
+                    description: >-
+                      Error identifier. For domain rejections and transport
+                      errors (`401`/`404`/`429`/`500`) this is a stable,
+                      machine-readable snake_case identifier that is part of the
+                      API contract and safe to branch on, e.g.
+                      `insufficient_margin`, `insufficient_balance`,
+                      `order_not_found`, `reduce_only_invalid`, `unauthorized`,
+                      `not_found`. For `400` it is a human-readable validation
+                      detail whose wording may change. See the Error handling
+                      guide for the domain identifiers. (Post-only /
+                      Fill-or-Kill outcomes are order statuses such as
+                      `post_only_rejected`, not rejections.)
+                    required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-106>
+            data:
+              oneOf:
+                - type: object
+                  required:
+                    - status
+                  properties:
+                    status:
+                      type: string
+                      enum:
+                        - ok
+                      x-parser-schema-id: <anonymous-schema-109>
+                  x-parser-schema-id: <anonymous-schema-108>
+                - type: object
+                  required:
+                    - status
+                    - error
+                  properties:
+                    status:
+                      type: string
+                      enum:
+                        - err
+                      x-parser-schema-id: <anonymous-schema-111>
+                    error:
+                      type: string
+                      description: >-
+                        Error identifier. For domain rejections and transport
+                        errors (`401`/`404`/`429`/`500`) this is a stable,
+                        machine-readable snake_case identifier that is part of
+                        the API contract and safe to branch on, e.g.
+                        `insufficient_margin`, `insufficient_balance`,
+                        `order_not_found`, `reduce_only_invalid`,
+                        `unauthorized`, `not_found`. For `400` it is a
+                        human-readable validation detail whose wording may
+                        change. See the Error handling guide for the domain
+                        identifiers. (Post-only / Fill-or-Kill outcomes are
+                        order statuses such as `post_only_rejected`, not
+                        rejections.)
+                      example: insufficient_margin
+                      x-parser-schema-id: <anonymous-schema-112>
+                  x-parser-schema-id: <anonymous-schema-110>
+              x-parser-schema-id: <anonymous-schema-107>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-105>
+        title: Auto-Cancel Response
+        description: Server responds with auto-cancel result
+        example: |-
+          {
+            "id": 5,
+            "data": {
+              "status": "ok"
+            }
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Response
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+receiveOperations:
+  - *ref_2
+sendMessages:
+  - *ref_3
+receiveMessages:
+  - *ref_4
+extensions:
+  - id: x-parser-unique-object-id
+    value: autoCancel
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-balances.md

@@ -0,0 +1,586 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Balances
+
+> Perps WebSocket private balance updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json balances
+id: balances
+title: Balances
+description: >-
+  Real-time balance updates. Pushed every 5 seconds. Requires authentication,
+  see [Auth](/ws/auth).
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: BalancesSubscribe
+    title: Balances subscribe
+    description: Subscribe to balances
+    type: receive
+    messages:
+      - &ref_6
+        id: SubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Subscribe
+            description: Subscribe to private balance updates (requires prior auth)
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Balances private channel: "balances"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - balances
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-514>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-515>
+            chs:
+              type: array
+              description: 'Balances private channel: "balances"'
+              items:
+                type: string
+                enum:
+                  - balances
+                x-parser-schema-id: <anonymous-schema-517>
+              example:
+                - balances
+              x-parser-schema-id: <anonymous-schema-516>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-513>
+        title: Subscribe
+        description: Subscribe to private balance updates (requires prior auth)
+        example: |-
+          {
+            "req": "sub",
+            "chs": [
+              "balances"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeRequest
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: balances
+  - &ref_3
+    id: BalancesSubscribeResponse
+    title: Balances subscribe response
+    description: Balances subscribe response
+    type: send
+    messages:
+      - &ref_8
+        id: SubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Subscribe Response
+            description: Response to balances subscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-519>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-523>
+                    x-parser-schema-id: <anonymous-schema-522>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-525>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-526>
+                    x-parser-schema-id: <anonymous-schema-524>
+                x-parser-schema-id: <anonymous-schema-521>
+              x-parser-schema-id: <anonymous-schema-520>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-518>
+        title: Subscribe Response
+        description: Response to balances subscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_2
+    id: BalancesUnsubscribe
+    title: Balances unsubscribe
+    description: Unsubscribe from balances
+    type: receive
+    messages:
+      - &ref_7
+        id: UnsubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Unsubscribe
+            description: Unsubscribe from private balance updates
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Balances private channel: "balances"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - balances
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-528>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-529>
+            chs:
+              type: array
+              description: 'Balances private channel: "balances"'
+              items:
+                type: string
+                enum:
+                  - balances
+                x-parser-schema-id: <anonymous-schema-531>
+              example:
+                - balances
+              x-parser-schema-id: <anonymous-schema-530>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-527>
+        title: Unsubscribe
+        description: Unsubscribe from private balance updates
+        example: |-
+          {
+            "req": "unsub",
+            "chs": [
+              "balances"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeRequest
+    bindings: []
+    extensions: *ref_0
+  - &ref_4
+    id: BalancesUnsubscribeResponse
+    title: Balances unsubscribe response
+    description: Balances unsubscribe response
+    type: send
+    messages:
+      - &ref_9
+        id: UnsubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Unsubscribe Response
+            description: Response to balances unsubscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-533>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-537>
+                    x-parser-schema-id: <anonymous-schema-536>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-539>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-540>
+                    x-parser-schema-id: <anonymous-schema-538>
+                x-parser-schema-id: <anonymous-schema-535>
+              x-parser-schema-id: <anonymous-schema-534>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-532>
+        title: Unsubscribe Response
+        description: Response to balances unsubscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_5
+    id: BalancesUpdate
+    title: Balances update
+    description: Receive balance updates
+    type: send
+    messages:
+      - &ref_10
+        id: Update
+        contentType: application/json
+        payload:
+          - name: Update
+            description: Balance updates pushed every 5 seconds
+            type: object
+            properties:
+              - name: ch
+                type: string
+                description: >-
+                  Channel name for push data. Parameterized channels include the
+                  instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                  "tickers::all"). Private channels use plain names (e.g.
+                  "fills", "orders").
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: sq
+                type: integer
+                description: Sequence number
+                required: true
+              - name: data
+                type: object
+                description: Balance object
+                required: true
+                properties:
+                  - name: asset
+                    type: string
+                    description: Asset name
+                    required: true
+                  - name: balance
+                    type: string
+                    description: Total balance
+                    required: true
+                  - name: value
+                    type: string
+                    description: USD value
+                    required: true
+        headers: []
+        jsonPayloadSchema:
+          title: Balances Update
+          type: object
+          properties:
+            ch:
+              type: string
+              description: >-
+                Channel name for push data. Parameterized channels include the
+                instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                "tickers::all"). Private channels use plain names (e.g. "fills",
+                "orders").
+              example: trades::1
+              x-parser-schema-id: <anonymous-schema-542>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-543>
+            sq:
+              type: integer
+              description: Sequence number
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-544>
+            data:
+              type: object
+              description: Balance object
+              properties:
+                asset:
+                  type: string
+                  description: Asset name
+                  example: USDC
+                  x-parser-schema-id: <anonymous-schema-546>
+                balance:
+                  type: string
+                  description: Total balance
+                  example: '10000.00'
+                  x-parser-schema-id: <anonymous-schema-547>
+                value:
+                  type: string
+                  description: USD value
+                  example: '10000.00'
+                  x-parser-schema-id: <anonymous-schema-548>
+              required:
+                - asset
+                - balance
+                - value
+              x-parser-schema-id: <anonymous-schema-545>
+          required:
+            - ch
+            - ts
+            - sq
+            - data
+          x-parser-schema-id: <anonymous-schema-541>
+        title: Update
+        description: Balance updates pushed every 5 seconds
+        example: |-
+          {
+            "ch": "balances",
+            "ts": 1767225600000,
+            "sq": 1234567890,
+            "data": {
+              "asset": "USDC",
+              "balance": "10000.00",
+              "value": "10000.00"
+            }
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Update
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+  - *ref_2
+receiveOperations:
+  - *ref_3
+  - *ref_4
+  - *ref_5
+sendMessages:
+  - *ref_6
+  - *ref_7
+receiveMessages:
+  - *ref_8
+  - *ref_9
+  - *ref_10
+extensions:
+  - id: x-parser-unique-object-id
+    value: balances
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-bbo.md

@@ -0,0 +1,606 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# BBO
+
+> Perps WebSocket best bid and offer updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json bbo
+id: bbo
+title: BBO
+description: Best bid and offer real-time updates.
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: BBOSubscribe
+    title: B b o subscribe
+    description: Subscribe to BBO
+    type: receive
+    messages:
+      - &ref_6
+        id: SubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Subscribe
+            description: Subscribe to BBO updates for a specific instrument
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: |
+                  BBO subscription per instrument: `bbo::{iid}` (e.g. `bbo::1`).
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-190>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-191>
+            chs:
+              type: array
+              description: |
+                BBO subscription per instrument: `bbo::{iid}` (e.g. `bbo::1`).
+              items:
+                type: string
+                pattern: ^bbo::\d+$
+                x-parser-schema-id: <anonymous-schema-193>
+              example:
+                - bbo::1
+              x-parser-schema-id: <anonymous-schema-192>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-189>
+        title: Subscribe
+        description: Subscribe to BBO updates for a specific instrument
+        example: |-
+          {
+            "req": "sub",
+            "chs": [
+              "bbo::1"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeRequest
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: bbo
+  - &ref_3
+    id: BBOSubscribeResponse
+    title: B b o subscribe response
+    description: BBO subscribe response
+    type: send
+    messages:
+      - &ref_8
+        id: SubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Subscribe Response
+            description: Response to BBO subscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-195>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-199>
+                    x-parser-schema-id: <anonymous-schema-198>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-201>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-202>
+                    x-parser-schema-id: <anonymous-schema-200>
+                x-parser-schema-id: <anonymous-schema-197>
+              x-parser-schema-id: <anonymous-schema-196>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-194>
+        title: Subscribe Response
+        description: Response to BBO subscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_2
+    id: BBOUnsubscribe
+    title: B b o unsubscribe
+    description: Unsubscribe from BBO
+    type: receive
+    messages:
+      - &ref_7
+        id: UnsubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Unsubscribe
+            description: Unsubscribe from BBO updates
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: |
+                  BBO subscription per instrument: `bbo::{iid}` (e.g. `bbo::1`).
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-204>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-205>
+            chs:
+              type: array
+              description: |
+                BBO subscription per instrument: `bbo::{iid}` (e.g. `bbo::1`).
+              items:
+                type: string
+                pattern: ^bbo::\d+$
+                x-parser-schema-id: <anonymous-schema-207>
+              example:
+                - bbo::1
+              x-parser-schema-id: <anonymous-schema-206>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-203>
+        title: Unsubscribe
+        description: Unsubscribe from BBO updates
+        example: |-
+          {
+            "req": "unsub",
+            "chs": [
+              "bbo::1"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeRequest
+    bindings: []
+    extensions: *ref_0
+  - &ref_4
+    id: BBOUnsubscribeResponse
+    title: B b o unsubscribe response
+    description: BBO unsubscribe response
+    type: send
+    messages:
+      - &ref_9
+        id: UnsubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Unsubscribe Response
+            description: Response to BBO unsubscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-209>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-213>
+                    x-parser-schema-id: <anonymous-schema-212>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-215>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-216>
+                    x-parser-schema-id: <anonymous-schema-214>
+                x-parser-schema-id: <anonymous-schema-211>
+              x-parser-schema-id: <anonymous-schema-210>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-208>
+        title: Unsubscribe Response
+        description: Response to BBO unsubscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_5
+    id: BBOUpdate
+    title: B b o update
+    description: Receive BBO updates
+    type: send
+    messages:
+      - &ref_10
+        id: Update
+        contentType: application/json
+        payload:
+          - name: Update
+            description: Real-time BBO updates for subscribed instruments
+            type: object
+            properties:
+              - name: ch
+                type: string
+                description: >-
+                  Channel name for push data. Parameterized channels include the
+                  instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                  "tickers::all"). Private channels use plain names (e.g.
+                  "fills", "orders").
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: sq
+                type: integer
+                description: Sequence number
+                required: true
+              - name: data
+                type: object
+                title: BBO Data
+                description: BBO object
+                required: true
+                properties:
+                  - name: iid
+                    type: integer
+                    description: Instrument ID
+                    required: true
+                  - name: bp
+                    type: string
+                    description: Best bid price
+                    required: true
+                  - name: bq
+                    type: string
+                    description: Best bid quantity
+                    required: true
+                  - name: ap
+                    type: string
+                    description: Best ask price
+                    required: true
+                  - name: aq
+                    type: string
+                    description: Best ask quantity
+                    required: true
+        headers: []
+        jsonPayloadSchema:
+          title: BBO Update
+          type: object
+          properties:
+            ch:
+              type: string
+              description: >-
+                Channel name for push data. Parameterized channels include the
+                instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                "tickers::all"). Private channels use plain names (e.g. "fills",
+                "orders").
+              example: trades::1
+              x-parser-schema-id: <anonymous-schema-218>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-219>
+            sq:
+              type: integer
+              description: Sequence number
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-220>
+            data:
+              type: object
+              description: BBO object
+              title: BBO Data
+              properties:
+                iid:
+                  type: integer
+                  description: Instrument ID
+                  example: 1
+                  x-parser-schema-id: <anonymous-schema-222>
+                bp:
+                  type: string
+                  description: Best bid price
+                  example: '99.50'
+                  x-parser-schema-id: <anonymous-schema-223>
+                bq:
+                  type: string
+                  description: Best bid quantity
+                  example: '10.00'
+                  x-parser-schema-id: <anonymous-schema-224>
+                ap:
+                  type: string
+                  description: Best ask price
+                  example: '100.50'
+                  x-parser-schema-id: <anonymous-schema-225>
+                aq:
+                  type: string
+                  description: Best ask quantity
+                  example: '10.00'
+                  x-parser-schema-id: <anonymous-schema-226>
+              required:
+                - iid
+                - bp
+                - bq
+                - ap
+                - aq
+              x-parser-schema-id: <anonymous-schema-221>
+          required:
+            - ch
+            - ts
+            - sq
+            - data
+          x-parser-schema-id: <anonymous-schema-217>
+        title: Update
+        description: Real-time BBO updates for subscribed instruments
+        example: |-
+          {
+            "ch": "bbo::1",
+            "ts": 1767225600000,
+            "sq": 1234567890,
+            "data": {
+              "iid": 1,
+              "bp": "99.50",
+              "bq": "10.00",
+              "ap": "100.50",
+              "aq": "10.00"
+            }
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Update
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+  - *ref_2
+receiveOperations:
+  - *ref_3
+  - *ref_4
+  - *ref_5
+sendMessages:
+  - *ref_6
+  - *ref_7
+receiveMessages:
+  - *ref_8
+  - *ref_9
+  - *ref_10
+extensions:
+  - id: x-parser-unique-object-id
+    value: bbo
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-book.md

@@ -0,0 +1,621 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Book
+
+> Perps WebSocket order book updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json book
+id: book
+title: Book
+description: Order book snapshot updates. Pushed every 100ms.
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: BookSubscribe
+    title: Book subscribe
+    description: Subscribe to book
+    type: receive
+    messages:
+      - &ref_6
+        id: SubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Subscribe
+            description: Subscribe to order book updates for an instrument
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: Book subscription in format "book::{iid}" (e.g., "book::1")
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-228>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-229>
+            chs:
+              type: array
+              description: Book subscription in format "book::{iid}" (e.g., "book::1")
+              items:
+                type: string
+                pattern: ^book::\d+$
+                x-parser-schema-id: <anonymous-schema-231>
+              example:
+                - book::1
+              x-parser-schema-id: <anonymous-schema-230>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-227>
+        title: Subscribe
+        description: Subscribe to order book updates for an instrument
+        example: |-
+          {
+            "req": "sub",
+            "chs": [
+              "book::1"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeRequest
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: book
+  - &ref_3
+    id: BookSubscribeResponse
+    title: Book subscribe response
+    description: Book subscribe response
+    type: send
+    messages:
+      - &ref_8
+        id: SubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Subscribe Response
+            description: Response to book subscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-233>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-237>
+                    x-parser-schema-id: <anonymous-schema-236>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-239>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-240>
+                    x-parser-schema-id: <anonymous-schema-238>
+                x-parser-schema-id: <anonymous-schema-235>
+              x-parser-schema-id: <anonymous-schema-234>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-232>
+        title: Subscribe Response
+        description: Response to book subscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_2
+    id: BookUnsubscribe
+    title: Book unsubscribe
+    description: Unsubscribe from book
+    type: receive
+    messages:
+      - &ref_7
+        id: UnsubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Unsubscribe
+            description: Unsubscribe from order book updates
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: Book subscription in format "book::{iid}" (e.g., "book::1")
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-242>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-243>
+            chs:
+              type: array
+              description: Book subscription in format "book::{iid}" (e.g., "book::1")
+              items:
+                type: string
+                pattern: ^book::\d+$
+                x-parser-schema-id: <anonymous-schema-245>
+              example:
+                - book::1
+              x-parser-schema-id: <anonymous-schema-244>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-241>
+        title: Unsubscribe
+        description: Unsubscribe from order book updates
+        example: |-
+          {
+            "req": "unsub",
+            "chs": [
+              "book::1"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeRequest
+    bindings: []
+    extensions: *ref_0
+  - &ref_4
+    id: BookUnsubscribeResponse
+    title: Book unsubscribe response
+    description: Book unsubscribe response
+    type: send
+    messages:
+      - &ref_9
+        id: UnsubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Unsubscribe Response
+            description: Response to book unsubscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-247>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-251>
+                    x-parser-schema-id: <anonymous-schema-250>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-253>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-254>
+                    x-parser-schema-id: <anonymous-schema-252>
+                x-parser-schema-id: <anonymous-schema-249>
+              x-parser-schema-id: <anonymous-schema-248>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-246>
+        title: Unsubscribe Response
+        description: Response to book unsubscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_5
+    id: BookUpdate
+    title: Book update
+    description: Receive book updates
+    type: send
+    messages:
+      - &ref_10
+        id: Update
+        contentType: application/json
+        payload:
+          - name: Update
+            description: Real-time order book updates for subscribed instruments
+            type: object
+            properties:
+              - name: ch
+                type: string
+                description: >-
+                  Channel name for push data. Parameterized channels include the
+                  instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                  "tickers::all"). Private channels use plain names (e.g.
+                  "fills", "orders").
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: sq
+                type: integer
+                description: Sequence number
+                required: true
+              - name: data
+                type: object
+                required: true
+                properties:
+                  - name: b
+                    type: array
+                    description: Bid levels
+                    required: true
+                    properties:
+                      - name: item
+                        type: array
+                        description: |
+                          - `"100.00"` - Price
+                          - `"10.00"` - Quantity
+                        required: false
+                        properties:
+                          - name: item
+                            type: string
+                            required: false
+                  - name: a
+                    type: array
+                    description: Ask levels
+                    required: true
+                    properties:
+                      - name: item
+                        type: array
+                        description: |
+                          - `"100.00"` - Price
+                          - `"10.00"` - Quantity
+                        required: false
+                        properties:
+                          - name: item
+                            type: string
+                            required: false
+        headers: []
+        jsonPayloadSchema:
+          title: Book Update
+          type: object
+          properties:
+            ch:
+              type: string
+              description: >-
+                Channel name for push data. Parameterized channels include the
+                instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                "tickers::all"). Private channels use plain names (e.g. "fills",
+                "orders").
+              example: trades::1
+              x-parser-schema-id: <anonymous-schema-256>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-257>
+            sq:
+              type: integer
+              description: Sequence number
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-258>
+            data:
+              type: object
+              required:
+                - b
+                - a
+              properties:
+                b:
+                  type: array
+                  items:
+                    type: array
+                    items:
+                      type: string
+                      x-parser-schema-id: <anonymous-schema-262>
+                    maxItems: 2
+                    description: |
+                      - `"100.00"` - Price
+                      - `"10.00"` - Quantity
+                    example:
+                      - '100.00'
+                      - '10.00'
+                    x-parser-schema-id: <anonymous-schema-261>
+                  description: Bid levels
+                  x-parser-schema-id: <anonymous-schema-260>
+                a:
+                  type: array
+                  items:
+                    type: array
+                    items:
+                      type: string
+                      x-parser-schema-id: <anonymous-schema-265>
+                    maxItems: 2
+                    description: |
+                      - `"100.00"` - Price
+                      - `"10.00"` - Quantity
+                    example:
+                      - '100.00'
+                      - '10.00'
+                    x-parser-schema-id: <anonymous-schema-264>
+                  description: Ask levels
+                  x-parser-schema-id: <anonymous-schema-263>
+              x-parser-schema-id: <anonymous-schema-259>
+          required:
+            - ch
+            - ts
+            - sq
+            - data
+          x-parser-schema-id: <anonymous-schema-255>
+        title: Update
+        description: Real-time order book updates for subscribed instruments
+        example: |-
+          {
+            "ch": "book::1",
+            "ts": 1767225600000,
+            "sq": 1234567890,
+            "data": {
+              "b": [
+                [
+                  "100.00",
+                  "10.00"
+                ]
+              ],
+              "a": [
+                [
+                  "100.00",
+                  "10.00"
+                ]
+              ]
+            }
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Update
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+  - *ref_2
+receiveOperations:
+  - *ref_3
+  - *ref_4
+  - *ref_5
+sendMessages:
+  - *ref_6
+  - *ref_7
+receiveMessages:
+  - *ref_8
+  - *ref_9
+  - *ref_10
+extensions:
+  - id: x-parser-unique-object-id
+    value: book
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-cancel-orders-coid.md

@@ -0,0 +1,406 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Cancel Orders by Client Order ID
+
+> Perps WebSocket order cancellation by client order ID.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json cancelOrdersCOID
+id: cancelOrdersCOID
+title: Cancel Orders COID
+description: |
+  Cancel orders by client order ID.
+  Requires proxy signature, see [proxy signing](/http/signing#2-proxy-signing).
+
+  <Badge color="gray" size="md">Action Weight: **0**</Badge>
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: CancelOrdersCOIDSend
+    title: Cancel orders c o i d send
+    description: Cancel orders by client order ID
+    type: receive
+    messages:
+      - &ref_3
+        id: Request
+        contentType: application/json
+        payload:
+          - name: Cancel Orders COID Request
+            description: Client submits a signed cancel-by-client-order-id request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: op
+                type: object
+                required: true
+                properties:
+                  - name: type
+                    type: string
+                    enumValues:
+                      - cancelOrdersCOID
+                    required: true
+                  - name: args
+                    type: array
+                    description: >
+                      Array of client order IDs to cancel. Cancelling an order
+                      that has
+
+                      attached take-profit / stop-loss children (see
+                      `CreateOrder.tr`)
+
+                      cascades to those children — they are cancelled with
+                      reason
+
+                      `ParentCancelled`.
+                    required: true
+                    properties:
+                      - name: item
+                        type: string
+                        description: Client order ID
+                        required: false
+              - name: sig
+                type: string
+                description: Signature in hex format
+                required: true
+              - name: salt
+                type: integer
+                description: Salt
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: exp
+                type: integer
+                description: >-
+                  Command expiry timestamp in Unix milliseconds. If provided, it
+                  must be in the future and within the gateway's default command
+                  timeout. It can shorten request validity but cannot extend it.
+                  This is not an order auto-cancel time.
+                required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-72>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-73>
+            op:
+              type: object
+              required:
+                - type
+                - args
+              properties:
+                type:
+                  type: string
+                  enum:
+                    - cancelOrdersCOID
+                  x-parser-schema-id: <anonymous-schema-75>
+                args:
+                  type: array
+                  description: >
+                    Array of client order IDs to cancel. Cancelling an order
+                    that has
+
+                    attached take-profit / stop-loss children (see
+                    `CreateOrder.tr`)
+
+                    cascades to those children — they are cancelled with reason
+
+                    `ParentCancelled`.
+                  items:
+                    type: string
+                    description: Client order ID
+                    minLength: 32
+                    maxLength: 32
+                    pattern: ^[0-9a-f]{32}$
+                    example: 550e8400e29b41d4a716446655440000
+                    x-parser-schema-id: <anonymous-schema-77>
+                  x-parser-schema-id: <anonymous-schema-76>
+              x-parser-schema-id: <anonymous-schema-74>
+            sig:
+              type: string
+              description: Signature in hex format
+              example: 0x1234567890...
+              x-parser-schema-id: <anonymous-schema-78>
+            salt:
+              type: integer
+              description: Salt
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-79>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-80>
+            exp:
+              type: integer
+              description: >-
+                Command expiry timestamp in Unix milliseconds. If provided, it
+                must be in the future and within the gateway's default command
+                timeout. It can shorten request validity but cannot extend it.
+                This is not an order auto-cancel time.
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-81>
+          required:
+            - req
+            - op
+            - sig
+            - salt
+            - ts
+          x-parser-schema-id: <anonymous-schema-71>
+        title: Cancel Orders COID Request
+        description: Client submits a signed cancel-by-client-order-id request
+        example: |-
+          {
+            "req": "post",
+            "op": {
+              "type": "cancelOrdersCOID",
+              "args": [
+                "550e8400e29b41d4a716446655440000"
+              ]
+            },
+            "sig": "0x1234567890...",
+            "salt": 1234567890,
+            "ts": 1767225600000,
+            "exp": 1767225600000
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Request
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: cancelOrdersCOID
+  - &ref_2
+    id: CancelOrdersCOIDReceive
+    title: Cancel orders c o i d receive
+    description: Cancel by client order ID response
+    type: send
+    messages:
+      - &ref_4
+        id: Response
+        contentType: application/json
+        payload:
+          - name: Cancel Orders COID Response
+            description: Server responds with cancel result for each client order ID
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                description: Array of cancel results
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: oid
+                        type: integer
+                        description: Order ID
+                        required: true
+                      - name: coid
+                        type: string
+                        description: Client order ID
+                        required: false
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: oid
+                        type: integer
+                        description: Order ID
+                        required: false
+                      - name: coid
+                        type: string
+                        description: Client order ID
+                        required: false
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-83>
+            data:
+              type: array
+              description: Array of cancel results
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                      - oid
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-87>
+                      oid:
+                        type: integer
+                        description: Order ID
+                        example: 1234567890
+                        x-parser-schema-id: <anonymous-schema-88>
+                      coid:
+                        type: string
+                        description: Client order ID
+                        minLength: 32
+                        maxLength: 32
+                        pattern: ^[0-9a-f]{32}$
+                        example: 550e8400e29b41d4a716446655440000
+                        x-parser-schema-id: <anonymous-schema-89>
+                    x-parser-schema-id: <anonymous-schema-86>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-91>
+                      oid:
+                        type: integer
+                        description: Order ID
+                        example: 1234567890
+                        x-parser-schema-id: <anonymous-schema-92>
+                      coid:
+                        type: string
+                        description: Client order ID
+                        minLength: 32
+                        maxLength: 32
+                        pattern: ^[0-9a-f]{32}$
+                        example: 550e8400e29b41d4a716446655440000
+                        x-parser-schema-id: <anonymous-schema-93>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-94>
+                    x-parser-schema-id: <anonymous-schema-90>
+                x-parser-schema-id: <anonymous-schema-85>
+              x-parser-schema-id: <anonymous-schema-84>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-82>
+        title: Cancel Orders COID Response
+        description: Server responds with cancel result for each client order ID
+        example: |-
+          {
+            "id": 3,
+            "data": [
+              {
+                "status": "ok",
+                "oid": 1234567890,
+                "coid": "550e8400e29b41d4a716446655440000"
+              },
+              {
+                "status": "ok",
+                "oid": 1234567891,
+                "coid": "550e8400e29b41d4a716446655440001"
+              }
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Response
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+receiveOperations:
+  - *ref_2
+sendMessages:
+  - *ref_3
+receiveMessages:
+  - *ref_4
+extensions:
+  - id: x-parser-unique-object-id
+    value: cancelOrdersCOID
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-cancel-orders.md

@@ -0,0 +1,398 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Cancel Orders
+
+> Perps WebSocket order cancellation by order ID.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json cancelOrders
+id: cancelOrders
+title: Cancel Orders
+description: |
+  Cancel orders.
+  Requires proxy signature, see [proxy signing](/http/signing#2-proxy-signing).
+
+  <Badge color="gray" size="md">Action Weight: **0**</Badge>
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: CancelOrdersSend
+    title: Cancel orders send
+    description: Cancel orders
+    type: receive
+    messages:
+      - &ref_3
+        id: Request
+        contentType: application/json
+        payload:
+          - name: Cancel Orders Request
+            description: Client submits a signed order cancellation request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: op
+                type: object
+                required: true
+                properties:
+                  - name: type
+                    type: string
+                    enumValues:
+                      - cancelOrders
+                    required: true
+                  - name: args
+                    type: array
+                    description: >
+                      Array of order IDs to cancel. Cancelling an order that has
+                      attached
+
+                      take-profit / stop-loss children (see `CreateOrder.tr`)
+                      cascades to
+
+                      those children — they are cancelled with reason
+                      `ParentCancelled`.
+                    required: true
+                    properties:
+                      - name: item
+                        type: integer
+                        description: Order ID
+                        required: false
+              - name: sig
+                type: string
+                description: Signature in hex format
+                required: true
+              - name: salt
+                type: integer
+                description: Salt
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: exp
+                type: integer
+                description: >-
+                  Command expiry timestamp in Unix milliseconds. If provided, it
+                  must be in the future and within the gateway's default command
+                  timeout. It can shorten request validity but cannot extend it.
+                  This is not an order auto-cancel time.
+                required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-48>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-49>
+            op:
+              type: object
+              required:
+                - type
+                - args
+              properties:
+                type:
+                  type: string
+                  enum:
+                    - cancelOrders
+                  x-parser-schema-id: <anonymous-schema-51>
+                args:
+                  type: array
+                  description: >
+                    Array of order IDs to cancel. Cancelling an order that has
+                    attached
+
+                    take-profit / stop-loss children (see `CreateOrder.tr`)
+                    cascades to
+
+                    those children — they are cancelled with reason
+                    `ParentCancelled`.
+                  items:
+                    type: integer
+                    description: Order ID
+                    example: 1234567890
+                    x-parser-schema-id: <anonymous-schema-53>
+                  x-parser-schema-id: <anonymous-schema-52>
+              x-parser-schema-id: <anonymous-schema-50>
+            sig:
+              type: string
+              description: Signature in hex format
+              example: 0x1234567890...
+              x-parser-schema-id: <anonymous-schema-54>
+            salt:
+              type: integer
+              description: Salt
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-55>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-56>
+            exp:
+              type: integer
+              description: >-
+                Command expiry timestamp in Unix milliseconds. If provided, it
+                must be in the future and within the gateway's default command
+                timeout. It can shorten request validity but cannot extend it.
+                This is not an order auto-cancel time.
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-57>
+          required:
+            - req
+            - op
+            - sig
+            - salt
+            - ts
+          x-parser-schema-id: <anonymous-schema-47>
+        title: Cancel Orders Request
+        description: Client submits a signed order cancellation request
+        example: |-
+          {
+            "req": "post",
+            "op": {
+              "type": "cancelOrders",
+              "args": [
+                1234567890
+              ]
+            },
+            "sig": "0x1234567890...",
+            "salt": 1234567890,
+            "ts": 1767225600000,
+            "exp": 1767225600000
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Request
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: cancelOrders
+  - &ref_2
+    id: CancelOrdersReceive
+    title: Cancel orders receive
+    description: Cancel response
+    type: send
+    messages:
+      - &ref_4
+        id: Response
+        contentType: application/json
+        payload:
+          - name: Cancel Orders Response
+            description: Server responds with cancel result for each order
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                description: Array of cancel results
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: oid
+                        type: integer
+                        description: Order ID
+                        required: true
+                      - name: coid
+                        type: string
+                        description: Client order ID
+                        required: false
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: oid
+                        type: integer
+                        description: Order ID
+                        required: false
+                      - name: coid
+                        type: string
+                        description: Client order ID
+                        required: false
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-59>
+            data:
+              type: array
+              description: Array of cancel results
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                      - oid
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-63>
+                      oid:
+                        type: integer
+                        description: Order ID
+                        example: 1234567890
+                        x-parser-schema-id: <anonymous-schema-64>
+                      coid:
+                        type: string
+                        description: Client order ID
+                        minLength: 32
+                        maxLength: 32
+                        pattern: ^[0-9a-f]{32}$
+                        example: 550e8400e29b41d4a716446655440000
+                        x-parser-schema-id: <anonymous-schema-65>
+                    x-parser-schema-id: <anonymous-schema-62>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-67>
+                      oid:
+                        type: integer
+                        description: Order ID
+                        example: 1234567890
+                        x-parser-schema-id: <anonymous-schema-68>
+                      coid:
+                        type: string
+                        description: Client order ID
+                        minLength: 32
+                        maxLength: 32
+                        pattern: ^[0-9a-f]{32}$
+                        example: 550e8400e29b41d4a716446655440000
+                        x-parser-schema-id: <anonymous-schema-69>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-70>
+                    x-parser-schema-id: <anonymous-schema-66>
+                x-parser-schema-id: <anonymous-schema-61>
+              x-parser-schema-id: <anonymous-schema-60>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-58>
+        title: Cancel Orders Response
+        description: Server responds with cancel result for each order
+        example: |-
+          {
+            "id": 3,
+            "data": [
+              {
+                "status": "ok",
+                "oid": 1234567890
+              },
+              {
+                "status": "ok",
+                "oid": 1234567891
+              }
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Response
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+receiveOperations:
+  - *ref_2
+sendMessages:
+  - *ref_3
+receiveMessages:
+  - *ref_4
+extensions:
+  - id: x-parser-unique-object-id
+    value: cancelOrders
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-deposits.md

@@ -0,0 +1,614 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Deposits
+
+> Perps WebSocket private deposit updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json deposits
+id: deposits
+title: Deposits
+description: >-
+  Real-time deposit status updates. Requires authentication, see
+  [Auth](/ws/auth).
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: DepositsSubscribe
+    title: Deposits subscribe
+    description: Subscribe to deposits
+    type: receive
+    messages:
+      - &ref_6
+        id: SubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Subscribe
+            description: Subscribe to private deposit updates (requires prior auth)
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Deposits private channel: "deposits"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - deposits
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-606>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-607>
+            chs:
+              type: array
+              description: 'Deposits private channel: "deposits"'
+              items:
+                type: string
+                enum:
+                  - deposits
+                x-parser-schema-id: <anonymous-schema-609>
+              example:
+                - deposits
+              x-parser-schema-id: <anonymous-schema-608>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-605>
+        title: Subscribe
+        description: Subscribe to private deposit updates (requires prior auth)
+        example: |-
+          {
+            "req": "sub",
+            "chs": [
+              "deposits"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeRequest
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: deposits
+  - &ref_3
+    id: DepositsSubscribeResponse
+    title: Deposits subscribe response
+    description: Deposits subscribe response
+    type: send
+    messages:
+      - &ref_8
+        id: SubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Subscribe Response
+            description: Response to deposits subscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-611>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-615>
+                    x-parser-schema-id: <anonymous-schema-614>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-617>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-618>
+                    x-parser-schema-id: <anonymous-schema-616>
+                x-parser-schema-id: <anonymous-schema-613>
+              x-parser-schema-id: <anonymous-schema-612>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-610>
+        title: Subscribe Response
+        description: Response to deposits subscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_2
+    id: DepositsUnsubscribe
+    title: Deposits unsubscribe
+    description: Unsubscribe from deposits
+    type: receive
+    messages:
+      - &ref_7
+        id: UnsubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Unsubscribe
+            description: Unsubscribe from private deposit updates
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Deposits private channel: "deposits"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - deposits
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-620>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-621>
+            chs:
+              type: array
+              description: 'Deposits private channel: "deposits"'
+              items:
+                type: string
+                enum:
+                  - deposits
+                x-parser-schema-id: <anonymous-schema-623>
+              example:
+                - deposits
+              x-parser-schema-id: <anonymous-schema-622>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-619>
+        title: Unsubscribe
+        description: Unsubscribe from private deposit updates
+        example: |-
+          {
+            "req": "unsub",
+            "chs": [
+              "deposits"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeRequest
+    bindings: []
+    extensions: *ref_0
+  - &ref_4
+    id: DepositsUnsubscribeResponse
+    title: Deposits unsubscribe response
+    description: Deposits unsubscribe response
+    type: send
+    messages:
+      - &ref_9
+        id: UnsubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Unsubscribe Response
+            description: Response to deposits unsubscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-625>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-629>
+                    x-parser-schema-id: <anonymous-schema-628>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-631>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-632>
+                    x-parser-schema-id: <anonymous-schema-630>
+                x-parser-schema-id: <anonymous-schema-627>
+              x-parser-schema-id: <anonymous-schema-626>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-624>
+        title: Unsubscribe Response
+        description: Response to deposits unsubscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_5
+    id: DepositsUpdate
+    title: Deposits update
+    description: Receive deposit updates
+    type: send
+    messages:
+      - &ref_10
+        id: Update
+        contentType: application/json
+        payload:
+          - name: Update
+            description: Deposit status updates for authenticated users
+            type: object
+            properties:
+              - name: ch
+                type: string
+                description: >-
+                  Channel name for push data. Parameterized channels include the
+                  instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                  "tickers::all"). Private channels use plain names (e.g.
+                  "fills", "orders").
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: sq
+                type: integer
+                description: Sequence number
+                required: true
+              - name: data
+                type: object
+                description: Array of deposit objects
+                required: true
+                properties:
+                  - name: hash
+                    type: string
+                    description: On-chain transaction hash, "0x" if not yet mined
+                    required: true
+                  - name: asset
+                    type: string
+                    description: Asset name
+                    required: true
+                  - name: amount
+                    type: string
+                    description: >-
+                      Raw token amount including decimals. For withdrawals this
+                      matches the uint256 amount in the EIP-712 signature (e.g.
+                      "100000000" for 100 USDC with 6 decimals).
+                    required: true
+                  - name: status
+                    type: string
+                    description: Deposit status
+                    enumValues:
+                      - pending
+                      - confirmed
+                      - removed
+                    required: true
+        headers: []
+        jsonPayloadSchema:
+          title: Deposits Update
+          type: object
+          properties:
+            ch:
+              type: string
+              description: >-
+                Channel name for push data. Parameterized channels include the
+                instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                "tickers::all"). Private channels use plain names (e.g. "fills",
+                "orders").
+              example: trades::1
+              x-parser-schema-id: <anonymous-schema-634>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-635>
+            sq:
+              type: integer
+              description: Sequence number
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-636>
+            data:
+              type: object
+              description: Array of deposit objects
+              properties:
+                hash:
+                  type: string
+                  description: On-chain transaction hash, "0x" if not yet mined
+                  default: 0x
+                  example: >-
+                    0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+                  x-parser-schema-id: <anonymous-schema-638>
+                asset:
+                  type: string
+                  description: Asset name
+                  example: USDC
+                  x-parser-schema-id: <anonymous-schema-639>
+                amount:
+                  type: string
+                  description: >-
+                    Raw token amount including decimals. For withdrawals this
+                    matches the uint256 amount in the EIP-712 signature (e.g.
+                    "100000000" for 100 USDC with 6 decimals).
+                  example: '100000000'
+                  x-parser-schema-id: <anonymous-schema-640>
+                status:
+                  type: string
+                  description: Deposit status
+                  enum:
+                    - pending
+                    - confirmed
+                    - removed
+                  x-parser-schema-id: <anonymous-schema-641>
+              required:
+                - hash
+                - asset
+                - amount
+                - status
+              x-parser-schema-id: <anonymous-schema-637>
+          required:
+            - ch
+            - ts
+            - sq
+            - data
+          x-parser-schema-id: <anonymous-schema-633>
+        title: Update
+        description: Deposit status updates for authenticated users
+        example: |-
+          {
+            "ch": "deposits",
+            "ts": 1767225600000,
+            "sq": 1234567890,
+            "data": [
+              {
+                "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
+                "asset": "USDC",
+                "amount": "100000000",
+                "status": "pending"
+              }
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Update
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+  - *ref_2
+receiveOperations:
+  - *ref_3
+  - *ref_4
+  - *ref_5
+sendMessages:
+  - *ref_6
+  - *ref_7
+receiveMessages:
+  - *ref_8
+  - *ref_9
+  - *ref_10
+extensions:
+  - id: x-parser-unique-object-id
+    value: deposits
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-fills.md

@@ -0,0 +1,727 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Fills
+
+> Perps WebSocket private fill updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json fills
+id: fills
+title: Fills
+description: Real-time fill updates. Requires authentication, see [Auth](/ws/auth).
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: FillsSubscribe
+    title: Fills subscribe
+    description: Subscribe to fills
+    type: receive
+    messages:
+      - &ref_6
+        id: SubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Subscribe
+            description: Subscribe to private fill updates (requires prior auth)
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Fills private channel: "fills"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - fills
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-380>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-381>
+            chs:
+              type: array
+              description: 'Fills private channel: "fills"'
+              items:
+                type: string
+                enum:
+                  - fills
+                x-parser-schema-id: <anonymous-schema-383>
+              example:
+                - fills
+              x-parser-schema-id: <anonymous-schema-382>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-379>
+        title: Subscribe
+        description: Subscribe to private fill updates (requires prior auth)
+        example: |-
+          {
+            "req": "sub",
+            "chs": [
+              "fills"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeRequest
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: fills
+  - &ref_3
+    id: FillsSubscribeResponse
+    title: Fills subscribe response
+    description: Fills subscribe response
+    type: send
+    messages:
+      - &ref_8
+        id: SubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Subscribe Response
+            description: Response to fills subscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-385>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-389>
+                    x-parser-schema-id: <anonymous-schema-388>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-391>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-392>
+                    x-parser-schema-id: <anonymous-schema-390>
+                x-parser-schema-id: <anonymous-schema-387>
+              x-parser-schema-id: <anonymous-schema-386>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-384>
+        title: Subscribe Response
+        description: Response to fills subscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_2
+    id: FillsUnsubscribe
+    title: Fills unsubscribe
+    description: Unsubscribe from fills
+    type: receive
+    messages:
+      - &ref_7
+        id: UnsubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Unsubscribe
+            description: Unsubscribe from private fill updates
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Fills private channel: "fills"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - fills
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-394>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-395>
+            chs:
+              type: array
+              description: 'Fills private channel: "fills"'
+              items:
+                type: string
+                enum:
+                  - fills
+                x-parser-schema-id: <anonymous-schema-397>
+              example:
+                - fills
+              x-parser-schema-id: <anonymous-schema-396>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-393>
+        title: Unsubscribe
+        description: Unsubscribe from private fill updates
+        example: |-
+          {
+            "req": "unsub",
+            "chs": [
+              "fills"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeRequest
+    bindings: []
+    extensions: *ref_0
+  - &ref_4
+    id: FillsUnsubscribeResponse
+    title: Fills unsubscribe response
+    description: Fills unsubscribe response
+    type: send
+    messages:
+      - &ref_9
+        id: UnsubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Unsubscribe Response
+            description: Response to fills unsubscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-399>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-403>
+                    x-parser-schema-id: <anonymous-schema-402>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-405>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-406>
+                    x-parser-schema-id: <anonymous-schema-404>
+                x-parser-schema-id: <anonymous-schema-401>
+              x-parser-schema-id: <anonymous-schema-400>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-398>
+        title: Unsubscribe Response
+        description: Response to fills unsubscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_5
+    id: FillsUpdate
+    title: Fills update
+    description: Receive fill updates
+    type: send
+    messages:
+      - &ref_10
+        id: Update
+        contentType: application/json
+        payload:
+          - name: Update
+            description: Real-time fill updates for authenticated users
+            type: object
+            properties:
+              - name: ch
+                type: string
+                description: >-
+                  Channel name for push data. Parameterized channels include the
+                  instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                  "tickers::all"). Private channels use plain names (e.g.
+                  "fills", "orders").
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: sq
+                type: integer
+                description: Sequence number
+                required: true
+              - name: data
+                type: object
+                description: Array of fill objects
+                required: true
+                properties:
+                  - name: tid
+                    type: integer
+                    description: Trade ID
+                    required: true
+                  - name: oid
+                    type: integer
+                    description: Order ID
+                    required: true
+                  - name: iid
+                    type: integer
+                    description: Instrument ID
+                    required: true
+                  - name: side
+                    type: string
+                    description: Side
+                    enumValues:
+                      - long
+                      - short
+                    required: true
+                  - name: p
+                    type: string
+                    description: Price
+                    required: true
+                  - name: qty
+                    type: string
+                    description: Quantity in no. of contracts
+                    required: true
+                  - name: taker
+                    type: boolean
+                    description: Whether this side was the taker
+                    required: true
+                  - name: fee
+                    type: string
+                    description: Fee amount for this trade side
+                    required: true
+                  - name: fea
+                    type: string
+                    description: Fee asset name
+                    required: true
+                  - name: psz
+                    type: string
+                    description: Position size before the fill
+                    required: true
+                  - name: pep
+                    type: string
+                    description: Position entry price before the fill
+                    required: true
+                  - name: pnl
+                    type: string
+                    description: PnL in USD
+                    required: true
+                  - name: liq
+                    type: boolean
+                    description: Whether the fill was a liquidation
+                    required: true
+                  - name: ts
+                    type: integer
+                    description: >-
+                      Request timestamp. Unix milliseconds for most operations;
+                      Unix seconds for withdrawals (must match the on-chain
+                      EIP-712 struct verified against block.timestamp).
+                    required: true
+                  - name: coid
+                    type: string
+                    description: Client order ID
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          title: Fills Update
+          type: object
+          properties:
+            ch:
+              type: string
+              description: >-
+                Channel name for push data. Parameterized channels include the
+                instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                "tickers::all"). Private channels use plain names (e.g. "fills",
+                "orders").
+              example: trades::1
+              x-parser-schema-id: <anonymous-schema-408>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-409>
+            sq:
+              type: integer
+              description: Sequence number
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-410>
+            data:
+              type: object
+              description: Array of fill objects
+              properties:
+                tid:
+                  type: integer
+                  description: Trade ID
+                  example: 1
+                  x-parser-schema-id: <anonymous-schema-412>
+                oid:
+                  type: integer
+                  description: Order ID
+                  example: 1234567890
+                  x-parser-schema-id: <anonymous-schema-413>
+                iid:
+                  type: integer
+                  description: Instrument ID
+                  example: 1
+                  x-parser-schema-id: <anonymous-schema-414>
+                side:
+                  type: string
+                  description: Side
+                  enum:
+                    - long
+                    - short
+                  x-parser-schema-id: <anonymous-schema-415>
+                p:
+                  type: string
+                  description: Price
+                  example: '100.00'
+                  x-parser-schema-id: <anonymous-schema-416>
+                qty:
+                  type: string
+                  description: Quantity in no. of contracts
+                  example: '10.00'
+                  x-parser-schema-id: <anonymous-schema-417>
+                taker:
+                  type: boolean
+                  description: Whether this side was the taker
+                  x-parser-schema-id: <anonymous-schema-418>
+                fee:
+                  type: string
+                  description: Fee amount for this trade side
+                  example: '1.25'
+                  x-parser-schema-id: <anonymous-schema-419>
+                fea:
+                  type: string
+                  description: Fee asset name
+                  example: USDC
+                  x-parser-schema-id: <anonymous-schema-420>
+                psz:
+                  type: string
+                  description: Position size before the fill
+                  example: '26.86'
+                  x-parser-schema-id: <anonymous-schema-421>
+                pep:
+                  type: string
+                  description: Position entry price before the fill
+                  example: '100.00'
+                  x-parser-schema-id: <anonymous-schema-422>
+                pnl:
+                  type: string
+                  description: PnL in USD
+                  example: '100.00'
+                  x-parser-schema-id: <anonymous-schema-423>
+                liq:
+                  type: boolean
+                  description: Whether the fill was a liquidation
+                  x-parser-schema-id: <anonymous-schema-424>
+                ts:
+                  type: integer
+                  description: >-
+                    Request timestamp. Unix milliseconds for most operations;
+                    Unix seconds for withdrawals (must match the on-chain
+                    EIP-712 struct verified against block.timestamp).
+                  example: 1767225600000
+                  x-parser-schema-id: <anonymous-schema-425>
+                coid:
+                  type: string
+                  description: Client order ID
+                  minLength: 32
+                  maxLength: 32
+                  pattern: ^[0-9a-f]{32}$
+                  example: 550e8400e29b41d4a716446655440000
+                  x-parser-schema-id: <anonymous-schema-426>
+              required:
+                - tid
+                - oid
+                - iid
+                - side
+                - p
+                - qty
+                - taker
+                - fee
+                - fea
+                - psz
+                - pep
+                - pnl
+                - ts
+                - liq
+              x-parser-schema-id: <anonymous-schema-411>
+          required:
+            - ch
+            - ts
+            - sq
+            - data
+          x-parser-schema-id: <anonymous-schema-407>
+        title: Update
+        description: Real-time fill updates for authenticated users
+        example: |-
+          {
+            "ch": "fills",
+            "ts": 1767225600000,
+            "sq": 1234567890,
+            "data": [
+              {
+                "tid": 1,
+                "oid": 1234567890,
+                "iid": 1,
+                "side": "long",
+                "p": "100.00",
+                "qty": "10.00",
+                "fee": "1.25",
+                "fea": "USDC",
+                "psz": "26.86",
+                "pep": "100.00",
+                "pnl": "100.00",
+                "ts": 1767225600000,
+                "coid": "550e8400e29b41d4a716446655440000"
+              }
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Update
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+  - *ref_2
+receiveOperations:
+  - *ref_3
+  - *ref_4
+  - *ref_5
+sendMessages:
+  - *ref_6
+  - *ref_7
+receiveMessages:
+  - *ref_8
+  - *ref_9
+  - *ref_10
+extensions:
+  - id: x-parser-unique-object-id
+    value: fills
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-funding.md

@@ -0,0 +1,631 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Funding
+
+> Perps WebSocket private funding updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json funding
+id: funding
+title: Funding
+description: >-
+  Real-time funding payment updates. Requires authentication, see
+  [Auth](/ws/auth).
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: FundingSubscribe
+    title: Funding subscribe
+    description: Subscribe to funding
+    type: receive
+    messages:
+      - &ref_6
+        id: SubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Subscribe
+            description: Subscribe to private funding payment updates (requires prior auth)
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Funding private channel: "funding"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - funding
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-475>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-476>
+            chs:
+              type: array
+              description: 'Funding private channel: "funding"'
+              items:
+                type: string
+                enum:
+                  - funding
+                x-parser-schema-id: <anonymous-schema-478>
+              example:
+                - funding
+              x-parser-schema-id: <anonymous-schema-477>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-474>
+        title: Subscribe
+        description: Subscribe to private funding payment updates (requires prior auth)
+        example: |-
+          {
+            "req": "sub",
+            "chs": [
+              "funding"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeRequest
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: funding
+  - &ref_3
+    id: FundingSubscribeResponse
+    title: Funding subscribe response
+    description: Funding subscribe response
+    type: send
+    messages:
+      - &ref_8
+        id: SubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Subscribe Response
+            description: Response to funding subscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-480>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-484>
+                    x-parser-schema-id: <anonymous-schema-483>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-486>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-487>
+                    x-parser-schema-id: <anonymous-schema-485>
+                x-parser-schema-id: <anonymous-schema-482>
+              x-parser-schema-id: <anonymous-schema-481>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-479>
+        title: Subscribe Response
+        description: Response to funding subscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_2
+    id: FundingUnsubscribe
+    title: Funding unsubscribe
+    description: Unsubscribe from funding
+    type: receive
+    messages:
+      - &ref_7
+        id: UnsubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Unsubscribe
+            description: Unsubscribe from private funding updates
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Funding private channel: "funding"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - funding
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-489>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-490>
+            chs:
+              type: array
+              description: 'Funding private channel: "funding"'
+              items:
+                type: string
+                enum:
+                  - funding
+                x-parser-schema-id: <anonymous-schema-492>
+              example:
+                - funding
+              x-parser-schema-id: <anonymous-schema-491>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-488>
+        title: Unsubscribe
+        description: Unsubscribe from private funding updates
+        example: |-
+          {
+            "req": "unsub",
+            "chs": [
+              "funding"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeRequest
+    bindings: []
+    extensions: *ref_0
+  - &ref_4
+    id: FundingUnsubscribeResponse
+    title: Funding unsubscribe response
+    description: Funding unsubscribe response
+    type: send
+    messages:
+      - &ref_9
+        id: UnsubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Unsubscribe Response
+            description: Response to funding unsubscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-494>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-498>
+                    x-parser-schema-id: <anonymous-schema-497>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-500>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-501>
+                    x-parser-schema-id: <anonymous-schema-499>
+                x-parser-schema-id: <anonymous-schema-496>
+              x-parser-schema-id: <anonymous-schema-495>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-493>
+        title: Unsubscribe Response
+        description: Response to funding unsubscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_5
+    id: FundingUpdate
+    title: Funding update
+    description: Receive funding updates
+    type: send
+    messages:
+      - &ref_10
+        id: Update
+        contentType: application/json
+        payload:
+          - name: Update
+            description: Real-time funding payment updates for authenticated users
+            type: object
+            properties:
+              - name: ch
+                type: string
+                description: >-
+                  Channel name for push data. Parameterized channels include the
+                  instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                  "tickers::all"). Private channels use plain names (e.g.
+                  "fills", "orders").
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: sq
+                type: integer
+                description: Sequence number
+                required: true
+              - name: data
+                type: object
+                description: Array of funding objects
+                required: true
+                properties:
+                  - name: iid
+                    type: integer
+                    description: Instrument ID
+                    required: true
+                  - name: sz
+                    type: string
+                    description: >-
+                      Signed position size in no. of contracts (positive = long,
+                      negative = short)
+                    required: true
+                  - name: fr
+                    type: string
+                    description: Funding rate
+                    required: true
+                  - name: fund
+                    type: string
+                    description: Funding paid in USD
+                    required: true
+                  - name: fua
+                    type: string
+                    description: Funding asset name
+                    required: true
+                  - name: ts
+                    type: integer
+                    description: >-
+                      Request timestamp. Unix milliseconds for most operations;
+                      Unix seconds for withdrawals (must match the on-chain
+                      EIP-712 struct verified against block.timestamp).
+                    required: true
+        headers: []
+        jsonPayloadSchema:
+          title: Funding Update
+          type: object
+          properties:
+            ch:
+              type: string
+              description: >-
+                Channel name for push data. Parameterized channels include the
+                instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                "tickers::all"). Private channels use plain names (e.g. "fills",
+                "orders").
+              example: trades::1
+              x-parser-schema-id: <anonymous-schema-503>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-504>
+            sq:
+              type: integer
+              description: Sequence number
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-505>
+            data:
+              type: object
+              description: Array of funding objects
+              properties:
+                iid:
+                  type: integer
+                  description: Instrument ID
+                  example: 1
+                  x-parser-schema-id: <anonymous-schema-507>
+                sz:
+                  type: string
+                  description: >-
+                    Signed position size in no. of contracts (positive = long,
+                    negative = short)
+                  example: '10.00'
+                  x-parser-schema-id: <anonymous-schema-508>
+                fr:
+                  type: string
+                  description: Funding rate
+                  example: '0.0001'
+                  x-parser-schema-id: <anonymous-schema-509>
+                fund:
+                  type: string
+                  description: Funding paid in USD
+                  example: '1.00'
+                  x-parser-schema-id: <anonymous-schema-510>
+                fua:
+                  type: string
+                  description: Funding asset name
+                  example: USDC
+                  x-parser-schema-id: <anonymous-schema-511>
+                ts:
+                  type: integer
+                  description: >-
+                    Request timestamp. Unix milliseconds for most operations;
+                    Unix seconds for withdrawals (must match the on-chain
+                    EIP-712 struct verified against block.timestamp).
+                  example: 1767225600000
+                  x-parser-schema-id: <anonymous-schema-512>
+              required:
+                - iid
+                - sz
+                - fr
+                - fund
+                - fua
+                - ts
+              x-parser-schema-id: <anonymous-schema-506>
+          required:
+            - ch
+            - ts
+            - sq
+            - data
+          x-parser-schema-id: <anonymous-schema-502>
+        title: Update
+        description: Real-time funding payment updates for authenticated users
+        example: |-
+          {
+            "ch": "funding",
+            "ts": 1767225600000,
+            "sq": 1234567890,
+            "data": [
+              {
+                "iid": 1,
+                "sz": "10.00",
+                "fr": "0.0001",
+                "fund": "1.00",
+                "fua": "USDC",
+                "ts": 1767225600000
+              }
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Update
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+  - *ref_2
+receiveOperations:
+  - *ref_3
+  - *ref_4
+  - *ref_5
+sendMessages:
+  - *ref_6
+  - *ref_7
+receiveMessages:
+  - *ref_8
+  - *ref_9
+  - *ref_10
+extensions:
+  - id: x-parser-unique-object-id
+    value: funding
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-klines.md

@@ -0,0 +1,590 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Klines
+
+> Perps WebSocket candle updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json klines
+id: klines
+title: Klines
+description: Real-time kline updates.
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: KlinesSubscribe
+    title: Klines subscribe
+    description: Subscribe to klines
+    type: receive
+    messages:
+      - &ref_6
+        id: SubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Subscribe
+            description: Subscribe to kline updates for an instrument and interval
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: >-
+                  Klines subscription in format "klines::{iid}::{interval}"
+                  (e.g., "klines::1::1m")
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-267>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-268>
+            chs:
+              type: array
+              description: >-
+                Klines subscription in format "klines::{iid}::{interval}" (e.g.,
+                "klines::1::1m")
+              items:
+                type: string
+                pattern: ^klines::\d+::(1m|5m|15m|30m|1h|4h|6h|12h|1d|1w)$
+                x-parser-schema-id: <anonymous-schema-270>
+              example:
+                - klines::1::1m
+              x-parser-schema-id: <anonymous-schema-269>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-266>
+        title: Subscribe
+        description: Subscribe to kline updates for an instrument and interval
+        example: |-
+          {
+            "req": "sub",
+            "chs": [
+              "klines::1::1m"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeRequest
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: klines
+  - &ref_3
+    id: KlinesSubscribeResponse
+    title: Klines subscribe response
+    description: Klines subscribe response
+    type: send
+    messages:
+      - &ref_8
+        id: SubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Subscribe Response
+            description: Response to klines subscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-272>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-276>
+                    x-parser-schema-id: <anonymous-schema-275>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-278>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-279>
+                    x-parser-schema-id: <anonymous-schema-277>
+                x-parser-schema-id: <anonymous-schema-274>
+              x-parser-schema-id: <anonymous-schema-273>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-271>
+        title: Subscribe Response
+        description: Response to klines subscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_2
+    id: KlinesUnsubscribe
+    title: Klines unsubscribe
+    description: Unsubscribe from klines
+    type: receive
+    messages:
+      - &ref_7
+        id: UnsubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Unsubscribe
+            description: Unsubscribe from kline updates
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: >-
+                  Klines subscription in format "klines::{iid}::{interval}"
+                  (e.g., "klines::1::1m")
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-281>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-282>
+            chs:
+              type: array
+              description: >-
+                Klines subscription in format "klines::{iid}::{interval}" (e.g.,
+                "klines::1::1m")
+              items:
+                type: string
+                pattern: ^klines::\d+::(1m|5m|15m|30m|1h|4h|6h|12h|1d|1w)$
+                x-parser-schema-id: <anonymous-schema-284>
+              example:
+                - klines::1::1m
+              x-parser-schema-id: <anonymous-schema-283>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-280>
+        title: Unsubscribe
+        description: Unsubscribe from kline updates
+        example: |-
+          {
+            "req": "unsub",
+            "chs": [
+              "klines::1::1m"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeRequest
+    bindings: []
+    extensions: *ref_0
+  - &ref_4
+    id: KlinesUnsubscribeResponse
+    title: Klines unsubscribe response
+    description: Klines unsubscribe response
+    type: send
+    messages:
+      - &ref_9
+        id: UnsubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Unsubscribe Response
+            description: Response to klines unsubscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-286>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-290>
+                    x-parser-schema-id: <anonymous-schema-289>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-292>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-293>
+                    x-parser-schema-id: <anonymous-schema-291>
+                x-parser-schema-id: <anonymous-schema-288>
+              x-parser-schema-id: <anonymous-schema-287>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-285>
+        title: Unsubscribe Response
+        description: Response to klines unsubscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_5
+    id: KlinesUpdate
+    title: Klines update
+    description: Receive kline updates
+    type: send
+    messages:
+      - &ref_10
+        id: Update
+        contentType: application/json
+        payload:
+          - name: Update
+            description: Real-time kline updates for subscribed instruments
+            type: object
+            properties:
+              - name: ch
+                type: string
+                description: >-
+                  Channel name for push data. Parameterized channels include the
+                  instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                  "tickers::all"). Private channels use plain names (e.g.
+                  "fills", "orders").
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: sq
+                type: integer
+                description: Sequence number
+                required: true
+              - name: data
+                type: array
+                description: Array of kline arrays
+                required: true
+                properties:
+                  - name: item
+                    type: array
+                    description: |
+                      - `1767225600000` - Open time
+                      - `"100.00"` - Open price
+                      - `"105.00"` - High price
+                      - `"99.00"` - Low price
+                      - `"102.00"` - Close price
+                      - `"500.00"` - Volume (base unit)
+                      - `42` - Number of trades
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          title: Kline Update
+          type: object
+          properties:
+            ch:
+              type: string
+              description: >-
+                Channel name for push data. Parameterized channels include the
+                instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                "tickers::all"). Private channels use plain names (e.g. "fills",
+                "orders").
+              example: trades::1
+              x-parser-schema-id: <anonymous-schema-295>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-296>
+            sq:
+              type: integer
+              description: Sequence number
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-297>
+            data:
+              type: array
+              description: Array of kline arrays
+              items:
+                type: array
+                description: |
+                  - `1767225600000` - Open time
+                  - `"100.00"` - Open price
+                  - `"105.00"` - High price
+                  - `"99.00"` - Low price
+                  - `"102.00"` - Close price
+                  - `"500.00"` - Volume (base unit)
+                  - `42` - Number of trades
+                example:
+                  - 1767225600000
+                  - '100.00'
+                  - '105.00'
+                  - '99.00'
+                  - '102.00'
+                  - '500.00'
+                  - 42
+                x-parser-schema-id: <anonymous-schema-299>
+              x-parser-schema-id: <anonymous-schema-298>
+          required:
+            - ch
+            - ts
+            - sq
+            - data
+          x-parser-schema-id: <anonymous-schema-294>
+        title: Update
+        description: Real-time kline updates for subscribed instruments
+        example: |-
+          {
+            "ch": "klines::1::1m",
+            "ts": 1767225600000,
+            "sq": 1234567890,
+            "data": [
+              [
+                1767225600000,
+                "100.00",
+                "105.00",
+                "99.00",
+                "102.00",
+                "500.00",
+                42
+              ]
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Update
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+  - *ref_2
+receiveOperations:
+  - *ref_3
+  - *ref_4
+  - *ref_5
+sendMessages:
+  - *ref_6
+  - *ref_7
+receiveMessages:
+  - *ref_8
+  - *ref_9
+  - *ref_10
+extensions:
+  - id: x-parser-unique-object-id
+    value: klines
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-orders.md

@@ -0,0 +1,716 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Orders
+
+> Perps WebSocket private order updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json orders
+id: orders
+title: Orders
+description: Real-time order updates. Requires authentication, see [Auth](/ws/auth).
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: OrdersSubscribe
+    title: Orders subscribe
+    description: Subscribe to orders
+    type: receive
+    messages:
+      - &ref_6
+        id: SubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Subscribe
+            description: Subscribe to private order updates (requires prior auth)
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Orders private channel: "orders"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - orders
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-428>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-429>
+            chs:
+              type: array
+              description: 'Orders private channel: "orders"'
+              items:
+                type: string
+                enum:
+                  - orders
+                x-parser-schema-id: <anonymous-schema-431>
+              example:
+                - orders
+              x-parser-schema-id: <anonymous-schema-430>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-427>
+        title: Subscribe
+        description: Subscribe to private order updates (requires prior auth)
+        example: |-
+          {
+            "req": "sub",
+            "chs": [
+              "orders"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeRequest
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: orders
+  - &ref_3
+    id: OrdersSubscribeResponse
+    title: Orders subscribe response
+    description: Orders subscribe response
+    type: send
+    messages:
+      - &ref_8
+        id: SubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Subscribe Response
+            description: Response to orders subscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-433>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-437>
+                    x-parser-schema-id: <anonymous-schema-436>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-439>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-440>
+                    x-parser-schema-id: <anonymous-schema-438>
+                x-parser-schema-id: <anonymous-schema-435>
+              x-parser-schema-id: <anonymous-schema-434>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-432>
+        title: Subscribe Response
+        description: Response to orders subscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_2
+    id: OrdersUnsubscribe
+    title: Orders unsubscribe
+    description: Unsubscribe from orders
+    type: receive
+    messages:
+      - &ref_7
+        id: UnsubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Unsubscribe
+            description: Unsubscribe from private order updates
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Orders private channel: "orders"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - orders
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-442>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-443>
+            chs:
+              type: array
+              description: 'Orders private channel: "orders"'
+              items:
+                type: string
+                enum:
+                  - orders
+                x-parser-schema-id: <anonymous-schema-445>
+              example:
+                - orders
+              x-parser-schema-id: <anonymous-schema-444>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-441>
+        title: Unsubscribe
+        description: Unsubscribe from private order updates
+        example: |-
+          {
+            "req": "unsub",
+            "chs": [
+              "orders"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeRequest
+    bindings: []
+    extensions: *ref_0
+  - &ref_4
+    id: OrdersUnsubscribeResponse
+    title: Orders unsubscribe response
+    description: Orders unsubscribe response
+    type: send
+    messages:
+      - &ref_9
+        id: UnsubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Unsubscribe Response
+            description: Response to orders unsubscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-447>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-451>
+                    x-parser-schema-id: <anonymous-schema-450>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-453>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-454>
+                    x-parser-schema-id: <anonymous-schema-452>
+                x-parser-schema-id: <anonymous-schema-449>
+              x-parser-schema-id: <anonymous-schema-448>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-446>
+        title: Unsubscribe Response
+        description: Response to orders unsubscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_5
+    id: OrdersUpdate
+    title: Orders update
+    description: Receive order updates
+    type: send
+    messages:
+      - &ref_10
+        id: Update
+        contentType: application/json
+        payload:
+          - name: Update
+            description: Real-time order updates for authenticated users
+            type: object
+            properties:
+              - name: ch
+                type: string
+                description: >-
+                  Channel name for push data. Parameterized channels include the
+                  instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                  "tickers::all"). Private channels use plain names (e.g.
+                  "fills", "orders").
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: sq
+                type: integer
+                description: Sequence number
+                required: true
+              - name: data
+                type: object
+                description: Order object
+                required: true
+                properties:
+                  - name: oid
+                    type: integer
+                    description: Order ID
+                    required: true
+                  - name: iid
+                    type: integer
+                    description: Instrument ID
+                    required: true
+                  - name: buy
+                    type: boolean
+                    description: Is buy
+                    required: true
+                  - name: p
+                    type: string
+                    description: Price
+                    required: true
+                  - name: qty
+                    type: string
+                    description: Quantity in no. of contracts
+                    required: true
+                  - name: tif
+                    type: string
+                    description: Time in force
+                    enumValues:
+                      - gtc
+                      - ioc
+                      - fok
+                    required: true
+                  - name: po
+                    type: boolean
+                    description: Post only
+                    required: true
+                  - name: ro
+                    type: boolean
+                    description: Reduce only
+                    required: true
+                  - name: rest
+                    type: string
+                    description: Resting quantity
+                    required: true
+                  - name: fill
+                    type: string
+                    description: Filled quantity
+                    required: true
+                  - name: cts
+                    type: integer
+                    description: Create timestamp in milliseconds
+                    required: true
+                  - name: uts
+                    type: integer
+                    description: Update timestamp in milliseconds
+                    required: true
+                  - name: status
+                    type: string
+                    description: Order status
+                    required: true
+                  - name: coid
+                    type: string
+                    description: Client order ID
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          title: Orders Update
+          type: object
+          properties:
+            ch:
+              type: string
+              description: >-
+                Channel name for push data. Parameterized channels include the
+                instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                "tickers::all"). Private channels use plain names (e.g. "fills",
+                "orders").
+              example: trades::1
+              x-parser-schema-id: <anonymous-schema-456>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-457>
+            sq:
+              type: integer
+              description: Sequence number
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-458>
+            data:
+              type: object
+              description: Order object
+              properties:
+                oid:
+                  type: integer
+                  description: Order ID
+                  example: 1234567890
+                  x-parser-schema-id: <anonymous-schema-460>
+                iid:
+                  type: integer
+                  description: Instrument ID
+                  example: 1
+                  x-parser-schema-id: <anonymous-schema-461>
+                buy:
+                  type: boolean
+                  description: Is buy
+                  example: true
+                  x-parser-schema-id: <anonymous-schema-462>
+                p:
+                  type: string
+                  description: Price
+                  example: '100.00'
+                  x-parser-schema-id: <anonymous-schema-463>
+                qty:
+                  type: string
+                  description: Quantity in no. of contracts
+                  example: '10.00'
+                  x-parser-schema-id: <anonymous-schema-464>
+                tif:
+                  type: string
+                  description: Time in force
+                  enum:
+                    - gtc
+                    - ioc
+                    - fok
+                  x-parser-schema-id: <anonymous-schema-465>
+                po:
+                  type: boolean
+                  description: Post only
+                  default: false
+                  example: false
+                  x-parser-schema-id: <anonymous-schema-466>
+                ro:
+                  type: boolean
+                  description: Reduce only
+                  example: false
+                  default: false
+                  x-parser-schema-id: <anonymous-schema-467>
+                rest:
+                  type: string
+                  description: Resting quantity
+                  example: '9.00'
+                  x-parser-schema-id: <anonymous-schema-468>
+                fill:
+                  type: string
+                  description: Filled quantity
+                  example: '1.00'
+                  x-parser-schema-id: <anonymous-schema-469>
+                cts:
+                  type: integer
+                  description: Create timestamp in milliseconds
+                  example: 1767225600000
+                  x-parser-schema-id: <anonymous-schema-470>
+                uts:
+                  type: integer
+                  description: Update timestamp in milliseconds
+                  example: 1767225600000
+                  x-parser-schema-id: <anonymous-schema-471>
+                status:
+                  type: string
+                  description: Order status
+                  example: open
+                  x-parser-schema-id: <anonymous-schema-472>
+                coid:
+                  type: string
+                  description: Client order ID
+                  minLength: 32
+                  maxLength: 32
+                  pattern: ^[0-9a-f]{32}$
+                  example: 550e8400e29b41d4a716446655440000
+                  x-parser-schema-id: <anonymous-schema-473>
+              required:
+                - oid
+                - iid
+                - buy
+                - p
+                - qty
+                - tif
+                - po
+                - ro
+                - status
+                - rest
+                - fill
+                - cts
+                - uts
+              x-parser-schema-id: <anonymous-schema-459>
+          required:
+            - ch
+            - ts
+            - sq
+            - data
+          x-parser-schema-id: <anonymous-schema-455>
+        title: Update
+        description: Real-time order updates for authenticated users
+        example: |-
+          {
+            "ch": "orders",
+            "ts": 1767225600000,
+            "sq": 1234567890,
+            "data": {
+              "oid": 1234567890,
+              "iid": 1,
+              "buy": true,
+              "p": "100.00",
+              "qty": "10.00",
+              "tif": "gtc",
+              "po": false,
+              "ro": false,
+              "rest": "9.00",
+              "fill": "1.00",
+              "cts": 1767225600000,
+              "uts": 1767225600000,
+              "status": "open",
+              "coid": "550e8400e29b41d4a716446655440000"
+            }
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Update
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+  - *ref_2
+receiveOperations:
+  - *ref_3
+  - *ref_4
+  - *ref_5
+sendMessages:
+  - *ref_6
+  - *ref_7
+receiveMessages:
+  - *ref_8
+  - *ref_9
+  - *ref_10
+extensions:
+  - id: x-parser-unique-object-id
+    value: orders
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-ping.md

@@ -0,0 +1,222 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Ping
+
+> Perps WebSocket heartbeat.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json ping
+id: ping
+title: Ping
+description: >-
+  Connections are automatically closed after 60 seconds of inactivity. Send a
+  ping message periodically to keep the connection alive.
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: PingSend
+    title: Ping send
+    description: Send ping
+    type: receive
+    messages:
+      - &ref_3
+        id: Request
+        contentType: application/json
+        payload:
+          - name: Ping
+            description: Client sends ping to test connection and keep alive
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: op
+                type: object
+                required: true
+                properties:
+                  - name: type
+                    type: string
+                    enumValues:
+                      - ping
+                    required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-2>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-3>
+            op:
+              type: object
+              required:
+                - type
+              properties:
+                type:
+                  type: string
+                  enum:
+                    - ping
+                  x-parser-schema-id: <anonymous-schema-5>
+              x-parser-schema-id: <anonymous-schema-4>
+          required:
+            - req
+            - op
+          x-parser-schema-id: <anonymous-schema-1>
+        title: Ping
+        description: Client sends ping to test connection and keep alive
+        example: |-
+          {
+            "req": "post",
+            "op": {
+              "type": "ping"
+            }
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Request
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: ping
+  - &ref_2
+    id: PingReceive
+    title: Ping receive
+    description: Pong response
+    type: send
+    messages:
+      - &ref_4
+        id: Response
+        contentType: application/json
+        payload:
+          - name: Pong
+            description: Server responds with pong including connection info
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: object
+                required: true
+                properties:
+                  - name: status
+                    type: string
+                    description: Result status
+                    enumValues:
+                      - ok
+                      - err
+                    required: true
+                  - name: ts
+                    type: integer
+                    description: >-
+                      Request timestamp. Unix milliseconds for most operations;
+                      Unix seconds for withdrawals (must match the on-chain
+                      EIP-712 struct verified against block.timestamp).
+                    required: true
+                  - name: sq
+                    type: integer
+                    description: Sequence number
+                    required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-7>
+            data:
+              type: object
+              required:
+                - status
+                - ts
+                - sq
+              properties:
+                status:
+                  type: string
+                  enum:
+                    - ok
+                    - err
+                  description: Result status
+                  x-parser-schema-id: <anonymous-schema-9>
+                ts:
+                  type: integer
+                  description: >-
+                    Request timestamp. Unix milliseconds for most operations;
+                    Unix seconds for withdrawals (must match the on-chain
+                    EIP-712 struct verified against block.timestamp).
+                  example: 1767225600000
+                  x-parser-schema-id: <anonymous-schema-10>
+                sq:
+                  type: integer
+                  description: Sequence number
+                  example: 1234567890
+                  x-parser-schema-id: <anonymous-schema-11>
+              x-parser-schema-id: <anonymous-schema-8>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-6>
+        title: Pong
+        description: Server responds with pong including connection info
+        example: |-
+          {
+            "data": {
+              "status": "ok",
+              "ts": 1767225600000,
+              "sq": 1234567890
+            }
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Response
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+receiveOperations:
+  - *ref_2
+sendMessages:
+  - *ref_3
+receiveMessages:
+  - *ref_4
+extensions:
+  - id: x-parser-unique-object-id
+    value: ping
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-place-orders.md

@@ -0,0 +1,478 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Place Orders
+
+> Perps WebSocket order placement.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json placeOrders
+id: placeOrders
+title: Create Orders
+description: |
+  Create new orders.
+  Requires proxy signature, see [proxy signing](/http/signing#2-proxy-signing).
+
+  <Badge color="gray" size="md">Action Weight: **1 / order**</Badge>
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: PlaceOrdersSend
+    title: Place orders send
+    description: Submit new orders
+    type: receive
+    messages:
+      - &ref_3
+        id: Request
+        contentType: application/json
+        payload:
+          - name: Create Orders Request
+            description: Client submits a signed order placement request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: op
+                type: object
+                required: true
+                properties:
+                  - name: type
+                    type: string
+                    enumValues:
+                      - createOrders
+                    required: true
+                  - name: args
+                    type: object
+                    description: Array of orders to create
+                    required: true
+                    properties:
+                      - name: iid
+                        type: integer
+                        description: Instrument ID
+                        required: true
+                      - name: buy
+                        type: boolean
+                        description: Is buy
+                        required: true
+                      - name: p
+                        type: string
+                        description: Price
+                        required: false
+                      - name: qty
+                        type: string
+                        description: Quantity in no. of contracts
+                        required: true
+                      - name: tif
+                        type: string
+                        description: Time in force
+                        enumValues:
+                          - gtc
+                          - ioc
+                          - fok
+                        required: false
+                      - name: po
+                        type: boolean
+                        description: Post only
+                        required: false
+                      - name: ro
+                        type: boolean
+                        description: Reduce only
+                        required: false
+                      - name: c
+                        type: string
+                        description: Client order ID
+                        required: false
+                      - name: tr
+                        type: object
+                        description: Optional trigger attached to this order.
+                        required: false
+                        properties:
+                          - name: market
+                            type: boolean
+                            description: Whether the trigger executes as a market order
+                            required: false
+                          - name: trp
+                            type: string
+                            description: Trigger price
+                            required: false
+                          - name: tpsl
+                            type: string
+                            description: Trigger type
+                            enumValues:
+                              - tp
+                              - sl
+                            required: false
+                  - name: grp
+                    type: string
+                    description: TPSL grouping
+                    enumValues:
+                      - order
+                      - position
+                    required: false
+              - name: sig
+                type: string
+                description: Signature in hex format
+                required: true
+              - name: salt
+                type: integer
+                description: Salt
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: exp
+                type: integer
+                description: >-
+                  Command expiry timestamp in Unix milliseconds. If provided, it
+                  must be in the future and within the gateway's default command
+                  timeout. It can shorten request validity but cannot extend it.
+                  This is not an order auto-cancel time.
+                required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-13>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-14>
+            op:
+              type: object
+              required:
+                - type
+                - args
+              properties:
+                type:
+                  type: string
+                  enum:
+                    - createOrders
+                  x-parser-schema-id: <anonymous-schema-16>
+                args:
+                  description: Array of orders to create
+                  type: object
+                  required:
+                    - iid
+                    - buy
+                    - qty
+                  properties:
+                    iid:
+                      type: integer
+                      description: Instrument ID
+                      example: 1
+                      x-parser-schema-id: <anonymous-schema-18>
+                    buy:
+                      type: boolean
+                      description: Is buy
+                      example: true
+                      x-parser-schema-id: <anonymous-schema-19>
+                    p:
+                      type: string
+                      description: Price
+                      example: '100.00'
+                      x-parser-schema-id: <anonymous-schema-20>
+                    qty:
+                      type: string
+                      description: Quantity in no. of contracts
+                      example: '10.00'
+                      x-parser-schema-id: <anonymous-schema-21>
+                    tif:
+                      type: string
+                      description: Time in force
+                      enum:
+                        - gtc
+                        - ioc
+                        - fok
+                      x-parser-schema-id: <anonymous-schema-22>
+                    po:
+                      type: boolean
+                      description: Post only
+                      default: false
+                      example: false
+                      x-parser-schema-id: <anonymous-schema-23>
+                    ro:
+                      type: boolean
+                      description: Reduce only
+                      example: false
+                      default: false
+                      x-parser-schema-id: <anonymous-schema-24>
+                    c:
+                      type: string
+                      description: Client order ID
+                      minLength: 32
+                      maxLength: 32
+                      pattern: ^[0-9a-f]{32}$
+                      example: 550e8400e29b41d4a716446655440000
+                      x-parser-schema-id: <anonymous-schema-25>
+                    tr:
+                      type: object
+                      description: Optional trigger attached to this order.
+                      properties:
+                        market:
+                          type: boolean
+                          description: Whether the trigger executes as a market order
+                          x-parser-schema-id: <anonymous-schema-27>
+                        trp:
+                          type: string
+                          description: Trigger price
+                          example: '110.00'
+                          x-parser-schema-id: <anonymous-schema-28>
+                        tpsl:
+                          type: string
+                          description: Trigger type
+                          enum:
+                            - tp
+                            - sl
+                          x-parser-schema-id: <anonymous-schema-29>
+                      x-parser-schema-id: <anonymous-schema-26>
+                  x-parser-schema-id: <anonymous-schema-17>
+                grp:
+                  type: string
+                  description: TPSL grouping
+                  enum:
+                    - order
+                    - position
+                  x-parser-schema-id: <anonymous-schema-30>
+              x-parser-schema-id: <anonymous-schema-15>
+            sig:
+              type: string
+              description: Signature in hex format
+              example: 0x1234567890...
+              x-parser-schema-id: <anonymous-schema-31>
+            salt:
+              type: integer
+              description: Salt
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-32>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-33>
+            exp:
+              type: integer
+              description: >-
+                Command expiry timestamp in Unix milliseconds. If provided, it
+                must be in the future and within the gateway's default command
+                timeout. It can shorten request validity but cannot extend it.
+                This is not an order auto-cancel time.
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-34>
+          required:
+            - req
+            - op
+            - sig
+            - salt
+            - ts
+          x-parser-schema-id: <anonymous-schema-12>
+        title: Create Orders Request
+        description: Client submits a signed order placement request
+        example: |-
+          {
+            "req": "post",
+            "op": {
+              "type": "createOrders",
+              "args": [
+                {
+                  "iid": 1,
+                  "buy": true,
+                  "p": "100.00",
+                  "qty": "10.00",
+                  "tif": "gtc",
+                  "po": false,
+                  "ro": false,
+                  "c": "550e8400e29b41d4a716446655440000",
+                  "tr": {
+                    "trp": "110.00",
+                    "tpsl": "tp"
+                  }
+                }
+              ],
+              "grp": "order"
+            },
+            "sig": "0x1234567890...",
+            "salt": 1234567890,
+            "ts": 1767225600000,
+            "exp": 1767225600000
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Request
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: placeOrders
+  - &ref_2
+    id: PlaceOrdersReceive
+    title: Place orders receive
+    description: Order ACK response
+    type: send
+    messages:
+      - &ref_4
+        id: Response
+        contentType: application/json
+        payload:
+          - name: Create Orders Response
+            description: Server responds with order ACK for each submitted order
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: object
+                description: Array of order results
+                required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-36>
+            data:
+              type: object
+              description: Array of order results
+              oneOf:
+                - type: object
+                  required:
+                    - status
+                    - oid
+                  properties:
+                    status:
+                      type: string
+                      enum:
+                        - ok
+                      x-parser-schema-id: <anonymous-schema-39>
+                    oid:
+                      type: integer
+                      description: Order ID
+                      example: 1234567890
+                      x-parser-schema-id: <anonymous-schema-40>
+                    coid:
+                      type: string
+                      description: Client order ID
+                      minLength: 32
+                      maxLength: 32
+                      pattern: ^[0-9a-f]{32}$
+                      example: 550e8400e29b41d4a716446655440000
+                      x-parser-schema-id: <anonymous-schema-41>
+                  x-parser-schema-id: <anonymous-schema-38>
+                - type: object
+                  required:
+                    - status
+                    - error
+                  properties:
+                    status:
+                      type: string
+                      enum:
+                        - err
+                      x-parser-schema-id: <anonymous-schema-43>
+                    error:
+                      type: string
+                      description: >-
+                        Error identifier. For domain rejections and transport
+                        errors (`401`/`404`/`429`/`500`) this is a stable,
+                        machine-readable snake_case identifier that is part of
+                        the API contract and safe to branch on, e.g.
+                        `insufficient_margin`, `insufficient_balance`,
+                        `order_not_found`, `reduce_only_invalid`,
+                        `unauthorized`, `not_found`. For `400` it is a
+                        human-readable validation detail whose wording may
+                        change. See the Error handling guide for the domain
+                        identifiers. (Post-only / Fill-or-Kill outcomes are
+                        order statuses such as `post_only_rejected`, not
+                        rejections.)
+                      example: insufficient_margin
+                      x-parser-schema-id: <anonymous-schema-44>
+                    oid:
+                      type: integer
+                      description: Order ID
+                      example: 1234567890
+                      x-parser-schema-id: <anonymous-schema-45>
+                    coid:
+                      type: string
+                      description: Client order ID
+                      minLength: 32
+                      maxLength: 32
+                      pattern: ^[0-9a-f]{32}$
+                      example: 550e8400e29b41d4a716446655440000
+                      x-parser-schema-id: <anonymous-schema-46>
+                  x-parser-schema-id: <anonymous-schema-42>
+              x-parser-schema-id: <anonymous-schema-37>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-35>
+        title: Create Orders Response
+        description: Server responds with order ACK for each submitted order
+        example: |-
+          {
+            "id": 1,
+            "data": [
+              {
+                "status": "ok",
+                "oid": 1234567890
+              }
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Response
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+receiveOperations:
+  - *ref_2
+sendMessages:
+  - *ref_3
+receiveMessages:
+  - *ref_4
+extensions:
+  - id: x-parser-unique-object-id
+    value: placeOrders
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-portfolio.md

@@ -0,0 +1,798 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Portfolio
+
+> Perps WebSocket private portfolio updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json portfolio
+id: portfolio
+title: Portfolio
+description: >-
+  Real-time portfolio updates. Pushed every 5 seconds. Requires authentication,
+  see [Auth](/ws/auth).
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: PortfolioSubscribe
+    title: Portfolio subscribe
+    description: Subscribe to portfolio
+    type: receive
+    messages:
+      - &ref_6
+        id: SubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Subscribe
+            description: Subscribe to private portfolio updates (requires prior auth)
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Portfolio private channel: "portfolio"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - portfolio
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-550>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-551>
+            chs:
+              type: array
+              description: 'Portfolio private channel: "portfolio"'
+              items:
+                type: string
+                enum:
+                  - portfolio
+                x-parser-schema-id: <anonymous-schema-553>
+              example:
+                - portfolio
+              x-parser-schema-id: <anonymous-schema-552>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-549>
+        title: Subscribe
+        description: Subscribe to private portfolio updates (requires prior auth)
+        example: |-
+          {
+            "req": "sub",
+            "chs": [
+              "portfolio"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeRequest
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: portfolio
+  - &ref_3
+    id: PortfolioSubscribeResponse
+    title: Portfolio subscribe response
+    description: Portfolio subscribe response
+    type: send
+    messages:
+      - &ref_8
+        id: SubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Subscribe Response
+            description: Response to portfolio subscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-555>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-559>
+                    x-parser-schema-id: <anonymous-schema-558>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-561>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-562>
+                    x-parser-schema-id: <anonymous-schema-560>
+                x-parser-schema-id: <anonymous-schema-557>
+              x-parser-schema-id: <anonymous-schema-556>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-554>
+        title: Subscribe Response
+        description: Response to portfolio subscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_2
+    id: PortfolioUnsubscribe
+    title: Portfolio unsubscribe
+    description: Unsubscribe from portfolio
+    type: receive
+    messages:
+      - &ref_7
+        id: UnsubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Unsubscribe
+            description: Unsubscribe from private portfolio updates
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Portfolio private channel: "portfolio"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - portfolio
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-564>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-565>
+            chs:
+              type: array
+              description: 'Portfolio private channel: "portfolio"'
+              items:
+                type: string
+                enum:
+                  - portfolio
+                x-parser-schema-id: <anonymous-schema-567>
+              example:
+                - portfolio
+              x-parser-schema-id: <anonymous-schema-566>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-563>
+        title: Unsubscribe
+        description: Unsubscribe from private portfolio updates
+        example: |-
+          {
+            "req": "unsub",
+            "chs": [
+              "portfolio"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeRequest
+    bindings: []
+    extensions: *ref_0
+  - &ref_4
+    id: PortfolioUnsubscribeResponse
+    title: Portfolio unsubscribe response
+    description: Portfolio unsubscribe response
+    type: send
+    messages:
+      - &ref_9
+        id: UnsubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Unsubscribe Response
+            description: Response to portfolio unsubscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-569>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-573>
+                    x-parser-schema-id: <anonymous-schema-572>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-575>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-576>
+                    x-parser-schema-id: <anonymous-schema-574>
+                x-parser-schema-id: <anonymous-schema-571>
+              x-parser-schema-id: <anonymous-schema-570>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-568>
+        title: Unsubscribe Response
+        description: Response to portfolio unsubscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_5
+    id: PortfolioUpdate
+    title: Portfolio update
+    description: Receive portfolio updates
+    type: send
+    messages:
+      - &ref_10
+        id: Update
+        contentType: application/json
+        payload:
+          - name: Update
+            description: Portfolio updates pushed every 5 seconds
+            type: object
+            properties:
+              - name: ch
+                type: string
+                description: >-
+                  Channel name for push data. Parameterized channels include the
+                  instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                  "tickers::all"). Private channels use plain names (e.g.
+                  "fills", "orders").
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: sq
+                type: integer
+                description: Sequence number
+                required: true
+              - name: data
+                type: object
+                required: true
+                properties:
+                  - name: positions
+                    type: array
+                    required: true
+                    properties:
+                      - name: instrument_id
+                        type: integer
+                        description: Instrument ID
+                        required: true
+                      - name: symbol
+                        type: string
+                        description: Instrument symbol
+                        required: true
+                      - name: size
+                        type: string
+                        description: >-
+                          Signed position size in no. of contracts (positive =
+                          long, negative = short)
+                        required: true
+                      - name: entry_price
+                        type: string
+                        description: Average entry price
+                        required: true
+                      - name: leverage
+                        type: integer
+                        description: Leverage
+                        required: true
+                      - name: cross
+                        type: boolean
+                        description: Whether to use cross margin mode
+                        required: true
+                      - name: initial_margin
+                        type: string
+                        description: Initial margin in USD
+                        required: true
+                      - name: maintenance_margin
+                        type: string
+                        description: Maintenance margin amount
+                        required: true
+                      - name: position_value
+                        type: string
+                        description: Notional position value in USD
+                        required: true
+                      - name: liquidation_price
+                        type: string
+                        description: Liquidation price
+                        required: true
+                      - name: unrealized_pnl
+                        type: string
+                        description: Unrealized PnL in USD
+                        required: true
+                      - name: return_on_equity
+                        type: string
+                        description: Return on equity as a decimal
+                        required: true
+                      - name: cumulative_funding
+                        type: string
+                        description: Cumulative funding paid/received in USD
+                        required: true
+                  - name: margin
+                    type: object
+                    required: true
+                    properties:
+                      - name: total_account_value
+                        type: string
+                        description: Total account value in USD (equity + unrealized PnL)
+                        required: true
+                      - name: total_initial_margin
+                        type: string
+                        description: Total initial margin in use across all positions
+                        required: true
+                      - name: total_maintenance_margin
+                        type: string
+                        description: Total maintenance margin across all positions
+                        required: true
+                      - name: total_position_value
+                        type: string
+                        description: Total notional position value in USD
+                        required: true
+                  - name: withdrawable
+                    type: string
+                    description: Withdrawable balance in USD
+                    required: true
+                  - name: in_liquidation
+                    type: boolean
+                    description: Whether the account is currently under liquidation
+                    required: true
+                  - name: timestamp
+                    type: integer
+                    description: Update timestamp in milliseconds
+                    required: true
+        headers: []
+        jsonPayloadSchema:
+          title: Portfolio Update
+          type: object
+          properties:
+            ch:
+              type: string
+              description: >-
+                Channel name for push data. Parameterized channels include the
+                instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                "tickers::all"). Private channels use plain names (e.g. "fills",
+                "orders").
+              example: trades::1
+              x-parser-schema-id: <anonymous-schema-578>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-579>
+            sq:
+              type: integer
+              description: Sequence number
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-580>
+            data:
+              type: object
+              required:
+                - positions
+                - margin
+                - withdrawable
+                - in_liquidation
+                - timestamp
+              properties:
+                positions:
+                  type: array
+                  items:
+                    type: object
+                    required:
+                      - instrument_id
+                      - symbol
+                      - size
+                      - entry_price
+                      - leverage
+                      - cross
+                      - initial_margin
+                      - maintenance_margin
+                      - position_value
+                      - liquidation_price
+                      - unrealized_pnl
+                      - return_on_equity
+                      - cumulative_funding
+                    properties:
+                      instrument_id:
+                        type: integer
+                        description: Instrument ID
+                        x-parser-schema-id: <anonymous-schema-584>
+                      symbol:
+                        type: string
+                        description: Instrument symbol
+                        example: NVDA-USDC
+                        x-parser-schema-id: <anonymous-schema-585>
+                      size:
+                        type: string
+                        description: >-
+                          Signed position size in no. of contracts (positive =
+                          long, negative = short)
+                        example: '10.00'
+                        x-parser-schema-id: <anonymous-schema-586>
+                      entry_price:
+                        type: string
+                        description: Average entry price
+                        example: '2986.30'
+                        x-parser-schema-id: <anonymous-schema-587>
+                      leverage:
+                        type: integer
+                        description: Leverage
+                        example: 10
+                        x-parser-schema-id: <anonymous-schema-588>
+                      cross:
+                        type: boolean
+                        description: Whether to use cross margin mode
+                        x-parser-schema-id: <anonymous-schema-589>
+                      initial_margin:
+                        type: string
+                        description: Initial margin in USD
+                        example: '10.00'
+                        x-parser-schema-id: <anonymous-schema-590>
+                      maintenance_margin:
+                        type: string
+                        description: Maintenance margin amount
+                        example: '100.00'
+                        x-parser-schema-id: <anonymous-schema-591>
+                      position_value:
+                        type: string
+                        description: Notional position value in USD
+                        example: '100.03'
+                        x-parser-schema-id: <anonymous-schema-592>
+                      liquidation_price:
+                        type: string
+                        description: Liquidation price
+                        example: '2866.27'
+                        x-parser-schema-id: <anonymous-schema-593>
+                      unrealized_pnl:
+                        type: string
+                        description: Unrealized PnL in USD
+                        example: '-0.01'
+                        x-parser-schema-id: <anonymous-schema-594>
+                      return_on_equity:
+                        type: string
+                        description: Return on equity as a decimal
+                        example: '-0.0027'
+                        x-parser-schema-id: <anonymous-schema-595>
+                      cumulative_funding:
+                        type: string
+                        description: Cumulative funding paid/received in USD
+                        example: '514.09'
+                        x-parser-schema-id: <anonymous-schema-596>
+                    x-parser-schema-id: <anonymous-schema-583>
+                  x-parser-schema-id: <anonymous-schema-582>
+                margin:
+                  type: object
+                  required:
+                    - total_account_value
+                    - total_initial_margin
+                    - total_maintenance_margin
+                    - total_position_value
+                  properties:
+                    total_account_value:
+                      type: string
+                      description: Total account value in USD (equity + unrealized PnL)
+                      example: '13109.48'
+                      x-parser-schema-id: <anonymous-schema-598>
+                    total_initial_margin:
+                      type: string
+                      description: Total initial margin in use across all positions
+                      example: '4.97'
+                      x-parser-schema-id: <anonymous-schema-599>
+                    total_maintenance_margin:
+                      type: string
+                      description: Total maintenance margin across all positions
+                      example: '2.49'
+                      x-parser-schema-id: <anonymous-schema-600>
+                    total_position_value:
+                      type: string
+                      description: Total notional position value in USD
+                      example: '100.03'
+                      x-parser-schema-id: <anonymous-schema-601>
+                  x-parser-schema-id: <anonymous-schema-597>
+                withdrawable:
+                  type: string
+                  description: Withdrawable balance in USD
+                  example: '13104.51'
+                  x-parser-schema-id: <anonymous-schema-602>
+                in_liquidation:
+                  type: boolean
+                  description: Whether the account is currently under liquidation
+                  x-parser-schema-id: <anonymous-schema-603>
+                timestamp:
+                  type: integer
+                  description: Update timestamp in milliseconds
+                  example: 1767225600000
+                  x-parser-schema-id: <anonymous-schema-604>
+              x-parser-schema-id: <anonymous-schema-581>
+          required:
+            - ch
+            - ts
+            - sq
+            - data
+          x-parser-schema-id: <anonymous-schema-577>
+        title: Update
+        description: Portfolio updates pushed every 5 seconds
+        example: |-
+          {
+            "ch": "portfolio",
+            "ts": 1767225600000,
+            "sq": 1234567890,
+            "data": {
+              "positions": [
+                {
+                  "symbol": "NVDA-USDC",
+                  "size": "10.00",
+                  "entry_price": "2986.30",
+                  "leverage": 10,
+                  "initial_margin": "10.00",
+                  "maintenance_margin": "100.00",
+                  "position_value": "100.03",
+                  "liquidation_price": "2866.27",
+                  "unrealized_pnl": "-0.01",
+                  "return_on_equity": "-0.0027",
+                  "cumulative_funding": "514.09"
+                }
+              ],
+              "margin": {
+                "total_account_value": "13109.48",
+                "total_initial_margin": "4.97",
+                "total_maintenance_margin": "2.49",
+                "total_position_value": "100.03"
+              },
+              "withdrawable": "13104.51",
+              "timestamp": 1767225600000
+            }
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Update
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+  - *ref_2
+receiveOperations:
+  - *ref_3
+  - *ref_4
+  - *ref_5
+sendMessages:
+  - *ref_6
+  - *ref_7
+receiveMessages:
+  - *ref_8
+  - *ref_9
+  - *ref_10
+extensions:
+  - id: x-parser-unique-object-id
+    value: portfolio
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-statistics.md

@@ -0,0 +1,655 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Statistics
+
+> Perps WebSocket 24-hour statistics updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json statistics
+id: statistics
+title: Statistics
+description: 24-hour statistics updates. Pushed every 1 second.
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: StatisticsSubscribe
+    title: Statistics subscribe
+    description: Subscribe to statistics
+    type: receive
+    messages:
+      - &ref_6
+        id: SubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Subscribe
+            description: >-
+              Subscribe to 24-hour statistics updates for all instruments or a
+              specific one
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: >
+                  Statistics subscription: `statistics::all` for every active
+                  instrument,
+
+                  or `statistics::{iid}` (e.g. `statistics::1`) for a specific
+                  one.
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-342>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-343>
+            chs:
+              type: array
+              description: >
+                Statistics subscription: `statistics::all` for every active
+                instrument,
+
+                or `statistics::{iid}` (e.g. `statistics::1`) for a specific
+                one.
+              items:
+                type: string
+                pattern: ^statistics::(\d+|all)$
+                x-parser-schema-id: <anonymous-schema-345>
+              example:
+                - statistics::all
+              x-parser-schema-id: <anonymous-schema-344>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-341>
+        title: Subscribe
+        description: >-
+          Subscribe to 24-hour statistics updates for all instruments or a
+          specific one
+        example: |-
+          {
+            "req": "sub",
+            "chs": [
+              "statistics::all"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeRequest
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: statistics
+  - &ref_3
+    id: StatisticsSubscribeResponse
+    title: Statistics subscribe response
+    description: Statistics subscribe response
+    type: send
+    messages:
+      - &ref_8
+        id: SubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Subscribe Response
+            description: Response to statistics subscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-347>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-351>
+                    x-parser-schema-id: <anonymous-schema-350>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-353>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-354>
+                    x-parser-schema-id: <anonymous-schema-352>
+                x-parser-schema-id: <anonymous-schema-349>
+              x-parser-schema-id: <anonymous-schema-348>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-346>
+        title: Subscribe Response
+        description: Response to statistics subscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_2
+    id: StatisticsUnsubscribe
+    title: Statistics unsubscribe
+    description: Unsubscribe from statistics
+    type: receive
+    messages:
+      - &ref_7
+        id: UnsubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Unsubscribe
+            description: Unsubscribe from statistics updates
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: >
+                  Statistics subscription: `statistics::all` for every active
+                  instrument,
+
+                  or `statistics::{iid}` (e.g. `statistics::1`) for a specific
+                  one.
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-356>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-357>
+            chs:
+              type: array
+              description: >
+                Statistics subscription: `statistics::all` for every active
+                instrument,
+
+                or `statistics::{iid}` (e.g. `statistics::1`) for a specific
+                one.
+              items:
+                type: string
+                pattern: ^statistics::(\d+|all)$
+                x-parser-schema-id: <anonymous-schema-359>
+              example:
+                - statistics::all
+              x-parser-schema-id: <anonymous-schema-358>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-355>
+        title: Unsubscribe
+        description: Unsubscribe from statistics updates
+        example: |-
+          {
+            "req": "unsub",
+            "chs": [
+              "statistics::all"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeRequest
+    bindings: []
+    extensions: *ref_0
+  - &ref_4
+    id: StatisticsUnsubscribeResponse
+    title: Statistics unsubscribe response
+    description: Statistics unsubscribe response
+    type: send
+    messages:
+      - &ref_9
+        id: UnsubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Unsubscribe Response
+            description: Response to statistics unsubscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-361>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-365>
+                    x-parser-schema-id: <anonymous-schema-364>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-367>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-368>
+                    x-parser-schema-id: <anonymous-schema-366>
+                x-parser-schema-id: <anonymous-schema-363>
+              x-parser-schema-id: <anonymous-schema-362>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-360>
+        title: Unsubscribe Response
+        description: Response to statistics unsubscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_5
+    id: StatisticsUpdate
+    title: Statistics update
+    description: Receive statistics updates
+    type: send
+    messages:
+      - &ref_10
+        id: Update
+        contentType: application/json
+        payload:
+          - name: Update
+            description: 24-hour statistics for subscribed instruments
+            type: object
+            properties:
+              - name: ch
+                type: string
+                description: >-
+                  Channel name for push data. Parameterized channels include the
+                  instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                  "tickers::all"). Private channels use plain names (e.g.
+                  "fills", "orders").
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: sq
+                type: integer
+                description: Sequence number
+                required: true
+              - name: data
+                type: object
+                description: Array of statistics objects
+                required: true
+                properties:
+                  - name: iid
+                    type: integer
+                    description: Instrument ID
+                    required: true
+                  - name: vol
+                    type: string
+                    description: 24-hour trading volume in contracts
+                    required: true
+                  - name: open
+                    type: string
+                    description: Opening price from 24 hours ago
+                    required: true
+                  - name: klines
+                    type: array
+                    description: Last 24-hour kline data
+                    required: true
+                    properties:
+                      - name: item
+                        type: array
+                        description: |
+                          - `1767225600000` - Open time
+                          - `"100.00"` - Open price
+                          - `"105.00"` - High price
+                          - `"99.00"` - Low price
+                          - `"102.00"` - Close price
+                          - `"500.00"` - Volume (base unit)
+                          - `42` - Number of trades
+                        required: false
+        headers: []
+        jsonPayloadSchema:
+          title: Statistics Update
+          type: object
+          properties:
+            ch:
+              type: string
+              description: >-
+                Channel name for push data. Parameterized channels include the
+                instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                "tickers::all"). Private channels use plain names (e.g. "fills",
+                "orders").
+              example: trades::1
+              x-parser-schema-id: <anonymous-schema-370>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-371>
+            sq:
+              type: integer
+              description: Sequence number
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-372>
+            data:
+              type: object
+              description: Array of statistics objects
+              properties:
+                iid:
+                  type: integer
+                  description: Instrument ID
+                  example: 1
+                  x-parser-schema-id: <anonymous-schema-374>
+                vol:
+                  type: string
+                  description: 24-hour trading volume in contracts
+                  example: '1000.00'
+                  x-parser-schema-id: <anonymous-schema-375>
+                open:
+                  type: string
+                  description: Opening price from 24 hours ago
+                  example: '100.50'
+                  x-parser-schema-id: <anonymous-schema-376>
+                klines:
+                  type: array
+                  items:
+                    type: array
+                    description: |
+                      - `1767225600000` - Open time
+                      - `"100.00"` - Open price
+                      - `"105.00"` - High price
+                      - `"99.00"` - Low price
+                      - `"102.00"` - Close price
+                      - `"500.00"` - Volume (base unit)
+                      - `42` - Number of trades
+                    example:
+                      - 1767225600000
+                      - '100.00'
+                      - '105.00'
+                      - '99.00'
+                      - '102.00'
+                      - '500.00'
+                      - 42
+                    x-parser-schema-id: <anonymous-schema-378>
+                  description: Last 24-hour kline data
+                  x-parser-schema-id: <anonymous-schema-377>
+              required:
+                - iid
+                - vol
+                - open
+                - klines
+              x-parser-schema-id: <anonymous-schema-373>
+          required:
+            - ch
+            - ts
+            - sq
+            - data
+          x-parser-schema-id: <anonymous-schema-369>
+        title: Update
+        description: 24-hour statistics for subscribed instruments
+        example: |-
+          {
+            "ch": "statistics::all",
+            "ts": 1767225600000,
+            "sq": 1234567890,
+            "data": [
+              {
+                "iid": 1,
+                "vol": "1000.00",
+                "open": "100.50",
+                "klines": [
+                  [
+                    1767225600000,
+                    "100.00",
+                    "105.00",
+                    "99.00",
+                    "102.00",
+                    "500.00",
+                    42
+                  ]
+                ]
+              }
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Update
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+  - *ref_2
+receiveOperations:
+  - *ref_3
+  - *ref_4
+  - *ref_5
+sendMessages:
+  - *ref_6
+  - *ref_7
+receiveMessages:
+  - *ref_8
+  - *ref_9
+  - *ref_10
+extensions:
+  - id: x-parser-unique-object-id
+    value: statistics
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-tickers.md

@@ -0,0 +1,647 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Tickers
+
+> Perps WebSocket ticker updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json tickers
+id: tickers
+title: Tickers
+description: Ticker updates. Pushed every 100ms.
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: TickersSubscribe
+    title: Tickers subscribe
+    description: Subscribe to tickers
+    type: receive
+    messages:
+      - &ref_6
+        id: SubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Subscribe
+            description: Subscribe to ticker updates for all instruments or a specific one
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: >
+                  Ticker subscription: `tickers::all` for every active
+                  instrument,
+
+                  or `tickers::{iid}` (e.g. `tickers::1`) for a specific one.
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-301>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-302>
+            chs:
+              type: array
+              description: |
+                Ticker subscription: `tickers::all` for every active instrument,
+                or `tickers::{iid}` (e.g. `tickers::1`) for a specific one.
+              items:
+                type: string
+                pattern: ^tickers::(\d+|all)$
+                x-parser-schema-id: <anonymous-schema-304>
+              example:
+                - tickers::all
+              x-parser-schema-id: <anonymous-schema-303>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-300>
+        title: Subscribe
+        description: Subscribe to ticker updates for all instruments or a specific one
+        example: |-
+          {
+            "req": "sub",
+            "chs": [
+              "tickers::all"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeRequest
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: tickers
+  - &ref_3
+    id: TickersSubscribeResponse
+    title: Tickers subscribe response
+    description: Tickers subscribe response
+    type: send
+    messages:
+      - &ref_8
+        id: SubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Subscribe Response
+            description: Response to tickers subscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-306>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-310>
+                    x-parser-schema-id: <anonymous-schema-309>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-312>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-313>
+                    x-parser-schema-id: <anonymous-schema-311>
+                x-parser-schema-id: <anonymous-schema-308>
+              x-parser-schema-id: <anonymous-schema-307>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-305>
+        title: Subscribe Response
+        description: Response to tickers subscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_2
+    id: TickersUnsubscribe
+    title: Tickers unsubscribe
+    description: Unsubscribe from tickers
+    type: receive
+    messages:
+      - &ref_7
+        id: UnsubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Unsubscribe
+            description: Unsubscribe from ticker updates
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: >
+                  Ticker subscription: `tickers::all` for every active
+                  instrument,
+
+                  or `tickers::{iid}` (e.g. `tickers::1`) for a specific one.
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-315>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-316>
+            chs:
+              type: array
+              description: |
+                Ticker subscription: `tickers::all` for every active instrument,
+                or `tickers::{iid}` (e.g. `tickers::1`) for a specific one.
+              items:
+                type: string
+                pattern: ^tickers::(\d+|all)$
+                x-parser-schema-id: <anonymous-schema-318>
+              example:
+                - tickers::all
+              x-parser-schema-id: <anonymous-schema-317>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-314>
+        title: Unsubscribe
+        description: Unsubscribe from ticker updates
+        example: |-
+          {
+            "req": "unsub",
+            "chs": [
+              "tickers::all"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeRequest
+    bindings: []
+    extensions: *ref_0
+  - &ref_4
+    id: TickersUnsubscribeResponse
+    title: Tickers unsubscribe response
+    description: Tickers unsubscribe response
+    type: send
+    messages:
+      - &ref_9
+        id: UnsubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Unsubscribe Response
+            description: Response to tickers unsubscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-320>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-324>
+                    x-parser-schema-id: <anonymous-schema-323>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-326>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-327>
+                    x-parser-schema-id: <anonymous-schema-325>
+                x-parser-schema-id: <anonymous-schema-322>
+              x-parser-schema-id: <anonymous-schema-321>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-319>
+        title: Unsubscribe Response
+        description: Response to tickers unsubscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_5
+    id: TickersUpdate
+    title: Tickers update
+    description: Receive ticker updates
+    type: send
+    messages:
+      - &ref_10
+        id: Update
+        contentType: application/json
+        payload:
+          - name: Update
+            description: Real-time ticker updates for subscribed instruments
+            type: object
+            properties:
+              - name: ch
+                type: string
+                description: >-
+                  Channel name for push data. Parameterized channels include the
+                  instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                  "tickers::all"). Private channels use plain names (e.g.
+                  "fills", "orders").
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: sq
+                type: integer
+                description: Sequence number
+                required: true
+              - name: data
+                type: object
+                description: Array of ticker objects
+                required: true
+                properties:
+                  - name: iid
+                    type: integer
+                    description: Instrument ID
+                    required: true
+                  - name: idx
+                    type: string
+                    description: Index price
+                    required: true
+                  - name: mark
+                    type: string
+                    description: Mark price
+                    required: true
+                  - name: last
+                    type: string
+                    description: Last traded price
+                    required: true
+                  - name: mid
+                    type: string
+                    description: Mid price
+                    required: true
+                  - name: oi
+                    type: string
+                    description: Open interest in number of contracts
+                    required: true
+                  - name: fr
+                    type: string
+                    description: Funding rate
+                    required: true
+                  - name: nxf
+                    type: integer
+                    description: Next funding timestamp in milliseconds
+                    required: true
+        headers: []
+        jsonPayloadSchema:
+          title: Ticker Update
+          type: object
+          properties:
+            ch:
+              type: string
+              description: >-
+                Channel name for push data. Parameterized channels include the
+                instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                "tickers::all"). Private channels use plain names (e.g. "fills",
+                "orders").
+              example: trades::1
+              x-parser-schema-id: <anonymous-schema-329>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-330>
+            sq:
+              type: integer
+              description: Sequence number
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-331>
+            data:
+              type: object
+              description: Array of ticker objects
+              properties:
+                iid:
+                  type: integer
+                  description: Instrument ID
+                  example: 1
+                  x-parser-schema-id: <anonymous-schema-333>
+                idx:
+                  type: string
+                  description: Index price
+                  example: '100.00'
+                  x-parser-schema-id: <anonymous-schema-334>
+                mark:
+                  type: string
+                  description: Mark price
+                  example: '100.00'
+                  x-parser-schema-id: <anonymous-schema-335>
+                last:
+                  type: string
+                  description: Last traded price
+                  example: '100.00'
+                  x-parser-schema-id: <anonymous-schema-336>
+                mid:
+                  type: string
+                  description: Mid price
+                  example: '100.00'
+                  x-parser-schema-id: <anonymous-schema-337>
+                oi:
+                  type: string
+                  description: Open interest in number of contracts
+                  example: '10.00'
+                  x-parser-schema-id: <anonymous-schema-338>
+                fr:
+                  type: string
+                  description: Funding rate
+                  example: '0.0001'
+                  x-parser-schema-id: <anonymous-schema-339>
+                nxf:
+                  type: integer
+                  description: Next funding timestamp in milliseconds
+                  example: 1767225600000
+                  x-parser-schema-id: <anonymous-schema-340>
+              required:
+                - iid
+                - idx
+                - mark
+                - last
+                - mid
+                - oi
+                - fr
+                - nxf
+              x-parser-schema-id: <anonymous-schema-332>
+          required:
+            - ch
+            - ts
+            - sq
+            - data
+          x-parser-schema-id: <anonymous-schema-328>
+        title: Update
+        description: Real-time ticker updates for subscribed instruments
+        example: |-
+          {
+            "ch": "tickers::all",
+            "ts": 1767225600000,
+            "sq": 1234567890,
+            "data": [
+              {
+                "iid": 1,
+                "idx": "100.00",
+                "mark": "100.00",
+                "last": "100.00",
+                "mid": "100.00",
+                "oi": "10.00",
+                "fr": "0.0001",
+                "nxf": 1767225600000
+              }
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Update
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+  - *ref_2
+receiveOperations:
+  - *ref_3
+  - *ref_4
+  - *ref_5
+sendMessages:
+  - *ref_6
+  - *ref_7
+receiveMessages:
+  - *ref_8
+  - *ref_9
+  - *ref_10
+extensions:
+  - id: x-parser-unique-object-id
+    value: tickers
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-trades.md

@@ -0,0 +1,647 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Trades
+
+> Perps WebSocket public trade updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json trades
+id: trades
+title: Trades
+description: Real-time trade stream.
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: TradesSubscribe
+    title: Trades subscribe
+    description: Subscribe to trades
+    type: receive
+    messages:
+      - &ref_6
+        id: SubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Subscribe
+            description: Subscribe to public trade updates for an instrument
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: >-
+                  Trades subscription in format "trades::{iid}" (e.g.,
+                  "trades::1")
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-150>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-151>
+            chs:
+              type: array
+              description: >-
+                Trades subscription in format "trades::{iid}" (e.g.,
+                "trades::1")
+              items:
+                type: string
+                pattern: ^trades::\d+$
+                x-parser-schema-id: <anonymous-schema-153>
+              example:
+                - trades::1
+              x-parser-schema-id: <anonymous-schema-152>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-149>
+        title: Subscribe
+        description: Subscribe to public trade updates for an instrument
+        example: |-
+          {
+            "req": "sub",
+            "chs": [
+              "trades::1"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeRequest
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: trades
+  - &ref_3
+    id: TradesSubscribeResponse
+    title: Trades subscribe response
+    description: Trades subscribe response
+    type: send
+    messages:
+      - &ref_8
+        id: SubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Subscribe Response
+            description: Response to trades subscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-155>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-159>
+                    x-parser-schema-id: <anonymous-schema-158>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-161>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-162>
+                    x-parser-schema-id: <anonymous-schema-160>
+                x-parser-schema-id: <anonymous-schema-157>
+              x-parser-schema-id: <anonymous-schema-156>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-154>
+        title: Subscribe Response
+        description: Response to trades subscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_2
+    id: TradesUnsubscribe
+    title: Trades unsubscribe
+    description: Unsubscribe from trades
+    type: receive
+    messages:
+      - &ref_7
+        id: UnsubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Unsubscribe
+            description: Unsubscribe from public trade updates
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: >-
+                  Trades subscription in format "trades::{iid}" (e.g.,
+                  "trades::1")
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-164>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-165>
+            chs:
+              type: array
+              description: >-
+                Trades subscription in format "trades::{iid}" (e.g.,
+                "trades::1")
+              items:
+                type: string
+                pattern: ^trades::\d+$
+                x-parser-schema-id: <anonymous-schema-167>
+              example:
+                - trades::1
+              x-parser-schema-id: <anonymous-schema-166>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-163>
+        title: Unsubscribe
+        description: Unsubscribe from public trade updates
+        example: |-
+          {
+            "req": "unsub",
+            "chs": [
+              "trades::1"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeRequest
+    bindings: []
+    extensions: *ref_0
+  - &ref_4
+    id: TradesUnsubscribeResponse
+    title: Trades unsubscribe response
+    description: Trades unsubscribe response
+    type: send
+    messages:
+      - &ref_9
+        id: UnsubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Unsubscribe Response
+            description: Response to trades unsubscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-169>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-173>
+                    x-parser-schema-id: <anonymous-schema-172>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-175>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-176>
+                    x-parser-schema-id: <anonymous-schema-174>
+                x-parser-schema-id: <anonymous-schema-171>
+              x-parser-schema-id: <anonymous-schema-170>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-168>
+        title: Unsubscribe Response
+        description: Response to trades unsubscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_5
+    id: TradesUpdate
+    title: Trades update
+    description: Receive trade updates
+    type: send
+    messages:
+      - &ref_10
+        id: Update
+        contentType: application/json
+        payload:
+          - name: Update
+            description: Real-time trade updates for subscribed instruments
+            type: object
+            properties:
+              - name: ch
+                type: string
+                description: >-
+                  Channel name for push data. Parameterized channels include the
+                  instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                  "tickers::all"). Private channels use plain names (e.g.
+                  "fills", "orders").
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: sq
+                type: integer
+                description: Sequence number
+                required: true
+              - name: data
+                type: object
+                title: TradeResponse
+                description: Array of trade objects
+                required: true
+                properties:
+                  - name: tid
+                    type: integer
+                    description: Trade ID
+                    required: true
+                  - name: iid
+                    type: integer
+                    description: Instrument ID
+                    required: true
+                  - name: side
+                    type: string
+                    description: Side
+                    enumValues:
+                      - long
+                      - short
+                    required: true
+                  - name: p
+                    type: string
+                    description: Price
+                    required: true
+                  - name: qty
+                    type: string
+                    description: Quantity in no. of contracts
+                    required: true
+                  - name: ts
+                    type: integer
+                    description: >-
+                      Request timestamp. Unix milliseconds for most operations;
+                      Unix seconds for withdrawals (must match the on-chain
+                      EIP-712 struct verified against block.timestamp).
+                    required: true
+                  - name: hash
+                    type: string
+                    description: On-chain transaction hash, "0x" if not yet mined
+                    required: true
+        headers: []
+        jsonPayloadSchema:
+          title: Trades Update
+          type: object
+          properties:
+            ch:
+              type: string
+              description: >-
+                Channel name for push data. Parameterized channels include the
+                instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                "tickers::all"). Private channels use plain names (e.g. "fills",
+                "orders").
+              example: trades::1
+              x-parser-schema-id: <anonymous-schema-178>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-179>
+            sq:
+              type: integer
+              description: Sequence number
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-180>
+            data:
+              type: object
+              description: Array of trade objects
+              title: TradeResponse
+              properties:
+                tid:
+                  type: integer
+                  description: Trade ID
+                  example: 1
+                  x-parser-schema-id: <anonymous-schema-182>
+                iid:
+                  type: integer
+                  description: Instrument ID
+                  example: 1
+                  x-parser-schema-id: <anonymous-schema-183>
+                side:
+                  type: string
+                  description: Side
+                  enum:
+                    - long
+                    - short
+                  x-parser-schema-id: <anonymous-schema-184>
+                p:
+                  type: string
+                  description: Price
+                  example: '100.00'
+                  x-parser-schema-id: <anonymous-schema-185>
+                qty:
+                  type: string
+                  description: Quantity in no. of contracts
+                  example: '10.00'
+                  x-parser-schema-id: <anonymous-schema-186>
+                ts:
+                  type: integer
+                  description: >-
+                    Request timestamp. Unix milliseconds for most operations;
+                    Unix seconds for withdrawals (must match the on-chain
+                    EIP-712 struct verified against block.timestamp).
+                  example: 1767225600000
+                  x-parser-schema-id: <anonymous-schema-187>
+                hash:
+                  type: string
+                  description: On-chain transaction hash, "0x" if not yet mined
+                  default: 0x
+                  example: >-
+                    0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+                  x-parser-schema-id: <anonymous-schema-188>
+              required:
+                - tid
+                - iid
+                - side
+                - p
+                - qty
+                - ts
+                - hash
+              x-parser-schema-id: <anonymous-schema-181>
+          required:
+            - ch
+            - ts
+            - sq
+            - data
+          x-parser-schema-id: <anonymous-schema-177>
+        title: Update
+        description: Real-time trade updates for subscribed instruments
+        example: |-
+          {
+            "ch": "trades::1",
+            "ts": 1767225600000,
+            "sq": 1234567890,
+            "data": [
+              {
+                "tid": 1,
+                "iid": 1,
+                "side": "long",
+                "p": "100.00",
+                "qty": "10.00",
+                "ts": 1767225600000,
+                "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
+              }
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Update
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+  - *ref_2
+receiveOperations:
+  - *ref_3
+  - *ref_4
+  - *ref_5
+sendMessages:
+  - *ref_6
+  - *ref_7
+receiveMessages:
+  - *ref_8
+  - *ref_9
+  - *ref_10
+extensions:
+  - id: x-parser-unique-object-id
+    value: trades
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-update-leverage.md

@@ -0,0 +1,325 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Update Leverage
+
+> Perps WebSocket leverage updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json updateLeverage
+id: updateLeverage
+title: Update Leverage
+description: |
+  Set leverage and margin type for an instrument.
+  Requires proxy signature, see [proxy signing](/http/signing#2-proxy-signing).
+
+  <Badge color="gray" size="md">Action Weight: **1**</Badge>
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: UpdateLeverageSend
+    title: Update leverage send
+    description: Update leverage
+    type: receive
+    messages:
+      - &ref_3
+        id: Request
+        contentType: application/json
+        payload:
+          - name: Update Leverage Request
+            description: Client submits a signed leverage update request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: op
+                type: object
+                required: true
+                properties:
+                  - name: type
+                    type: string
+                    enumValues:
+                      - updateLeverage
+                    required: true
+                  - name: args
+                    type: object
+                    required: true
+                    properties:
+                      - name: iid
+                        type: integer
+                        description: Instrument ID
+                        required: true
+                      - name: lev
+                        type: integer
+                        description: Leverage
+                        required: true
+                      - name: cross
+                        type: boolean
+                        description: Whether to use cross margin mode
+                        required: true
+              - name: sig
+                type: string
+                description: Signature in hex format
+                required: true
+              - name: salt
+                type: integer
+                description: Salt
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-114>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-115>
+            op:
+              type: object
+              required:
+                - type
+                - args
+              properties:
+                type:
+                  type: string
+                  enum:
+                    - updateLeverage
+                  x-parser-schema-id: <anonymous-schema-117>
+                args:
+                  type: object
+                  required:
+                    - iid
+                    - lev
+                    - cross
+                  properties:
+                    iid:
+                      type: integer
+                      description: Instrument ID
+                      example: 1
+                      x-parser-schema-id: <anonymous-schema-119>
+                    lev:
+                      type: integer
+                      description: Leverage
+                      example: 10
+                      x-parser-schema-id: <anonymous-schema-120>
+                    cross:
+                      type: boolean
+                      description: Whether to use cross margin mode
+                      x-parser-schema-id: <anonymous-schema-121>
+                  x-parser-schema-id: <anonymous-schema-118>
+              x-parser-schema-id: <anonymous-schema-116>
+            sig:
+              type: string
+              description: Signature in hex format
+              example: 0x1234567890...
+              x-parser-schema-id: <anonymous-schema-122>
+            salt:
+              type: integer
+              description: Salt
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-123>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-124>
+          required:
+            - req
+            - op
+            - sig
+            - salt
+            - ts
+          x-parser-schema-id: <anonymous-schema-113>
+        title: Update Leverage Request
+        description: Client submits a signed leverage update request
+        example: |-
+          {
+            "req": "post",
+            "op": {
+              "type": "updateLeverage",
+              "args": {
+                "iid": 1,
+                "lev": 10
+              }
+            },
+            "sig": "0x1234567890...",
+            "salt": 1234567890,
+            "ts": 1767225600000
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Request
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: updateLeverage
+  - &ref_2
+    id: UpdateLeverageReceive
+    title: Update leverage receive
+    description: Update leverage response
+    type: send
+    messages:
+      - &ref_4
+        id: Response
+        contentType: application/json
+        payload:
+          - name: Update Leverage Response
+            description: Server responds with leverage update result
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: object
+                required: true
+                properties:
+                  - name: status
+                    type: string
+                    enumValues:
+                      - ok
+                    required: true
+                  - name: status
+                    type: string
+                    enumValues:
+                      - err
+                    required: true
+                  - name: error
+                    type: string
+                    description: >-
+                      Error identifier. For domain rejections and transport
+                      errors (`401`/`404`/`429`/`500`) this is a stable,
+                      machine-readable snake_case identifier that is part of the
+                      API contract and safe to branch on, e.g.
+                      `insufficient_margin`, `insufficient_balance`,
+                      `order_not_found`, `reduce_only_invalid`, `unauthorized`,
+                      `not_found`. For `400` it is a human-readable validation
+                      detail whose wording may change. See the Error handling
+                      guide for the domain identifiers. (Post-only /
+                      Fill-or-Kill outcomes are order statuses such as
+                      `post_only_rejected`, not rejections.)
+                    required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-126>
+            data:
+              oneOf:
+                - type: object
+                  required:
+                    - status
+                  properties:
+                    status:
+                      type: string
+                      enum:
+                        - ok
+                      x-parser-schema-id: <anonymous-schema-129>
+                  x-parser-schema-id: <anonymous-schema-128>
+                - type: object
+                  required:
+                    - status
+                    - error
+                  properties:
+                    status:
+                      type: string
+                      enum:
+                        - err
+                      x-parser-schema-id: <anonymous-schema-131>
+                    error:
+                      type: string
+                      description: >-
+                        Error identifier. For domain rejections and transport
+                        errors (`401`/`404`/`429`/`500`) this is a stable,
+                        machine-readable snake_case identifier that is part of
+                        the API contract and safe to branch on, e.g.
+                        `insufficient_margin`, `insufficient_balance`,
+                        `order_not_found`, `reduce_only_invalid`,
+                        `unauthorized`, `not_found`. For `400` it is a
+                        human-readable validation detail whose wording may
+                        change. See the Error handling guide for the domain
+                        identifiers. (Post-only / Fill-or-Kill outcomes are
+                        order statuses such as `post_only_rejected`, not
+                        rejections.)
+                      example: insufficient_margin
+                      x-parser-schema-id: <anonymous-schema-132>
+                  x-parser-schema-id: <anonymous-schema-130>
+              x-parser-schema-id: <anonymous-schema-127>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-125>
+        title: Update Leverage Response
+        description: Server responds with leverage update result
+        example: |-
+          {
+            "id": 6,
+            "data": {
+              "status": "ok"
+            }
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Response
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+receiveOperations:
+  - *ref_2
+sendMessages:
+  - *ref_3
+receiveMessages:
+  - *ref_4
+extensions:
+  - id: x-parser-unique-object-id
+    value: updateLeverage
+securitySchemes: []
+
+````

docs/api-reference/wss/perps-withdrawals.md

@@ -0,0 +1,647 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Withdrawals
+
+> Perps WebSocket private withdrawal updates.
+
+
+
+## AsyncAPI
+
+````yaml asyncapi-perps.json withdrawals
+id: withdrawals
+title: Withdrawals
+description: >-
+  Real-time withdrawal status updates. Requires authentication, see
+  [Auth](/ws/auth).
+servers:
+  - id: production
+    protocol: wss
+    host: ws.perpetuals.polymarket.com
+    bindings: []
+    variables: []
+address: /v1/ws
+parameters: []
+bindings: []
+operations:
+  - &ref_1
+    id: WithdrawalsSubscribe
+    title: Withdrawals subscribe
+    description: Subscribe to withdrawals
+    type: receive
+    messages:
+      - &ref_6
+        id: SubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Subscribe
+            description: Subscribe to private withdrawal updates (requires prior auth)
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Withdrawals private channel: "withdrawals"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - withdrawals
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-643>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-644>
+            chs:
+              type: array
+              description: 'Withdrawals private channel: "withdrawals"'
+              items:
+                type: string
+                enum:
+                  - withdrawals
+                x-parser-schema-id: <anonymous-schema-646>
+              example:
+                - withdrawals
+              x-parser-schema-id: <anonymous-schema-645>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-642>
+        title: Subscribe
+        description: Subscribe to private withdrawal updates (requires prior auth)
+        example: |-
+          {
+            "req": "sub",
+            "chs": [
+              "withdrawals"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeRequest
+    bindings: []
+    extensions: &ref_0
+      - id: x-parser-unique-object-id
+        value: withdrawals
+  - &ref_3
+    id: WithdrawalsSubscribeResponse
+    title: Withdrawals subscribe response
+    description: Withdrawals subscribe response
+    type: send
+    messages:
+      - &ref_8
+        id: SubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Subscribe Response
+            description: Response to withdrawals subscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-648>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-652>
+                    x-parser-schema-id: <anonymous-schema-651>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-654>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-655>
+                    x-parser-schema-id: <anonymous-schema-653>
+                x-parser-schema-id: <anonymous-schema-650>
+              x-parser-schema-id: <anonymous-schema-649>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-647>
+        title: Subscribe Response
+        description: Response to withdrawals subscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: SubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_2
+    id: WithdrawalsUnsubscribe
+    title: Withdrawals unsubscribe
+    description: Unsubscribe from withdrawals
+    type: receive
+    messages:
+      - &ref_7
+        id: UnsubscribeRequest
+        contentType: application/json
+        payload:
+          - name: Unsubscribe
+            description: Unsubscribe from private withdrawal updates
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: req
+                type: string
+                description: Request type
+                enumValues:
+                  - post
+                  - sub
+                  - unsub
+                required: true
+              - name: chs
+                type: array
+                description: 'Withdrawals private channel: "withdrawals"'
+                required: true
+                properties:
+                  - name: item
+                    type: string
+                    enumValues:
+                      - withdrawals
+                    required: false
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Request
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-657>
+            req:
+              type: string
+              description: Request type
+              enum:
+                - post
+                - sub
+                - unsub
+              x-parser-schema-id: <anonymous-schema-658>
+            chs:
+              type: array
+              description: 'Withdrawals private channel: "withdrawals"'
+              items:
+                type: string
+                enum:
+                  - withdrawals
+                x-parser-schema-id: <anonymous-schema-660>
+              example:
+                - withdrawals
+              x-parser-schema-id: <anonymous-schema-659>
+          required:
+            - req
+            - chs
+          x-parser-schema-id: <anonymous-schema-656>
+        title: Unsubscribe
+        description: Unsubscribe from private withdrawal updates
+        example: |-
+          {
+            "req": "unsub",
+            "chs": [
+              "withdrawals"
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeRequest
+    bindings: []
+    extensions: *ref_0
+  - &ref_4
+    id: WithdrawalsUnsubscribeResponse
+    title: Withdrawals unsubscribe response
+    description: Withdrawals unsubscribe response
+    type: send
+    messages:
+      - &ref_9
+        id: UnsubscribeResponse
+        contentType: application/json
+        payload:
+          - name: Unsubscribe Response
+            description: Response to withdrawals unsubscribe request
+            type: object
+            properties:
+              - name: id
+                type: integer
+                description: Correlation ID for request-response matching
+                required: false
+              - name: data
+                type: array
+                title: Subscribe Response
+                required: true
+                properties:
+                  - name: item
+                    type: object
+                    required: false
+                    properties:
+                      - name: status
+                        type: string
+                        enumValues:
+                          - ok
+                        required: true
+                      - name: status
+                        type: string
+                        enumValues:
+                          - err
+                        required: true
+                      - name: error
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        required: true
+        headers: []
+        jsonPayloadSchema:
+          type: object
+          title: Base Response
+          properties:
+            id:
+              type: integer
+              description: Correlation ID for request-response matching
+              x-parser-schema-id: <anonymous-schema-662>
+            data:
+              title: Subscribe Response
+              type: array
+              items:
+                oneOf:
+                  - type: object
+                    required:
+                      - status
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - ok
+                        x-parser-schema-id: <anonymous-schema-666>
+                    x-parser-schema-id: <anonymous-schema-665>
+                  - type: object
+                    required:
+                      - status
+                      - error
+                    properties:
+                      status:
+                        type: string
+                        enum:
+                          - err
+                        x-parser-schema-id: <anonymous-schema-668>
+                      error:
+                        type: string
+                        description: >-
+                          Error identifier. For domain rejections and transport
+                          errors (`401`/`404`/`429`/`500`) this is a stable,
+                          machine-readable snake_case identifier that is part of
+                          the API contract and safe to branch on, e.g.
+                          `insufficient_margin`, `insufficient_balance`,
+                          `order_not_found`, `reduce_only_invalid`,
+                          `unauthorized`, `not_found`. For `400` it is a
+                          human-readable validation detail whose wording may
+                          change. See the Error handling guide for the domain
+                          identifiers. (Post-only / Fill-or-Kill outcomes are
+                          order statuses such as `post_only_rejected`, not
+                          rejections.)
+                        example: insufficient_margin
+                        x-parser-schema-id: <anonymous-schema-669>
+                    x-parser-schema-id: <anonymous-schema-667>
+                x-parser-schema-id: <anonymous-schema-664>
+              x-parser-schema-id: <anonymous-schema-663>
+          required:
+            - data
+          x-parser-schema-id: <anonymous-schema-661>
+        title: Unsubscribe Response
+        description: Response to withdrawals unsubscribe request
+        example: |-
+          {
+            "data": []
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: UnsubscribeResponse
+    bindings: []
+    extensions: *ref_0
+  - &ref_5
+    id: WithdrawalsUpdate
+    title: Withdrawals update
+    description: Receive withdrawal updates
+    type: send
+    messages:
+      - &ref_10
+        id: Update
+        contentType: application/json
+        payload:
+          - name: Update
+            description: Withdrawal status updates for authenticated users
+            type: object
+            properties:
+              - name: ch
+                type: string
+                description: >-
+                  Channel name for push data. Parameterized channels include the
+                  instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                  "tickers::all"). Private channels use plain names (e.g.
+                  "fills", "orders").
+                required: true
+              - name: ts
+                type: integer
+                description: >-
+                  Request timestamp. Unix milliseconds for most operations; Unix
+                  seconds for withdrawals (must match the on-chain EIP-712
+                  struct verified against block.timestamp).
+                required: true
+              - name: sq
+                type: integer
+                description: Sequence number
+                required: true
+              - name: data
+                type: object
+                description: Array of withdrawal objects
+                required: true
+                properties:
+                  - name: withdraw_id
+                    type: integer
+                    description: Withdraw ID
+                    required: true
+                  - name: asset
+                    type: string
+                    description: Asset name
+                    required: true
+                  - name: amount
+                    type: string
+                    description: >-
+                      Raw token amount including decimals. For withdrawals this
+                      matches the uint256 amount in the EIP-712 signature (e.g.
+                      "100000000" for 100 USDC with 6 decimals).
+                    required: true
+                  - name: fee
+                    type: string
+                    description: Withdrawal transaction fee in decimalized asset units
+                    required: true
+                  - name: to
+                    type: string
+                    description: Destination address in hex format
+                    required: true
+                  - name: status
+                    type: string
+                    description: Withdrawal status
+                    enumValues:
+                      - pending
+                      - confirmed
+                      - removed
+                      - failed
+                    required: true
+                  - name: hash
+                    type: string
+                    description: On-chain transaction hash, "0x" if not yet mined
+                    required: true
+        headers: []
+        jsonPayloadSchema:
+          title: Withdrawals Update
+          type: object
+          properties:
+            ch:
+              type: string
+              description: >-
+                Channel name for push data. Parameterized channels include the
+                instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
+                "tickers::all"). Private channels use plain names (e.g. "fills",
+                "orders").
+              example: trades::1
+              x-parser-schema-id: <anonymous-schema-671>
+            ts:
+              type: integer
+              description: >-
+                Request timestamp. Unix milliseconds for most operations; Unix
+                seconds for withdrawals (must match the on-chain EIP-712 struct
+                verified against block.timestamp).
+              example: 1767225600000
+              x-parser-schema-id: <anonymous-schema-672>
+            sq:
+              type: integer
+              description: Sequence number
+              example: 1234567890
+              x-parser-schema-id: <anonymous-schema-673>
+            data:
+              type: object
+              description: Array of withdrawal objects
+              properties:
+                withdraw_id:
+                  type: integer
+                  description: Withdraw ID
+                  x-parser-schema-id: <anonymous-schema-675>
+                asset:
+                  type: string
+                  description: Asset name
+                  example: USDC
+                  x-parser-schema-id: <anonymous-schema-676>
+                amount:
+                  type: string
+                  description: >-
+                    Raw token amount including decimals. For withdrawals this
+                    matches the uint256 amount in the EIP-712 signature (e.g.
+                    "100000000" for 100 USDC with 6 decimals).
+                  example: '100000000'
+                  x-parser-schema-id: <anonymous-schema-677>
+                fee:
+                  type: string
+                  description: Withdrawal transaction fee in decimalized asset units
+                  example: '5.00'
+                  x-parser-schema-id: <anonymous-schema-678>
+                to:
+                  type: string
+                  description: Destination address in hex format
+                  example: '0x1234567890abcdef1234567890abcdef12345678'
+                  x-parser-schema-id: <anonymous-schema-679>
+                status:
+                  type: string
+                  description: Withdrawal status
+                  enum:
+                    - pending
+                    - confirmed
+                    - removed
+                    - failed
+                  x-parser-schema-id: <anonymous-schema-680>
+                hash:
+                  type: string
+                  description: On-chain transaction hash, "0x" if not yet mined
+                  default: 0x
+                  example: >-
+                    0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+                  x-parser-schema-id: <anonymous-schema-681>
+              required:
+                - withdraw_id
+                - asset
+                - amount
+                - fee
+                - to
+                - status
+                - hash
+              x-parser-schema-id: <anonymous-schema-674>
+          required:
+            - ch
+            - ts
+            - sq
+            - data
+          x-parser-schema-id: <anonymous-schema-670>
+        title: Update
+        description: Withdrawal status updates for authenticated users
+        example: |-
+          {
+            "ch": "withdrawals",
+            "ts": 1767225600000,
+            "sq": 1234567890,
+            "data": [
+              {
+                "asset": "USDC",
+                "amount": "100000000",
+                "fee": "5.00",
+                "to": "0x1234567890abcdef1234567890abcdef12345678",
+                "status": "pending",
+                "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
+              }
+            ]
+          }
+        bindings: []
+        extensions:
+          - id: x-parser-unique-object-id
+            value: Update
+    bindings: []
+    extensions: *ref_0
+sendOperations:
+  - *ref_1
+  - *ref_2
+receiveOperations:
+  - *ref_3
+  - *ref_4
+  - *ref_5
+sendMessages:
+  - *ref_6
+  - *ref_7
+receiveMessages:
+  - *ref_8
+  - *ref_9
+  - *ref_10
+extensions:
+  - id: x-parser-unique-object-id
+    value: withdrawals
+securitySchemes: []
+
+````