diff --git a/TARGET.md b/TARGET.md
index 6556418..c9639d9 100644
--- a/TARGET.md
+++ b/TARGET.md
@@ -389,3 +389,100 @@ https://docs.polymarket.com/api-reference/core/get-user-combo-positions.md
https://docs.polymarket.com/api-reference/maker/cancel-a-quote.md
https://docs.polymarket.com/api-reference/maker/confirm-or-decline-last-look.md
https://docs.polymarket.com/api-reference/maker/submit-a-quote.md
+
+## NEW - Perps (2026-07-13)
+https://docs.polymarket.com/perps/overview.md
+https://docs.polymarket.com/perps/account-management.md
+https://docs.polymarket.com/perps/authenticated-sessions.md
+https://docs.polymarket.com/perps/changelog.md
+https://docs.polymarket.com/perps/concepts.md
+https://docs.polymarket.com/perps/faq.md
+https://docs.polymarket.com/perps/fund-your-account.md
+https://docs.polymarket.com/perps/market-data.md
+https://docs.polymarket.com/perps/overview.md
+https://docs.polymarket.com/perps/place-your-first-trade.md
+https://docs.polymarket.com/perps/rate-limits.md
+https://docs.polymarket.com/perps/realtime-updates.md
+https://docs.polymarket.com/perps/referral-program.md
+https://docs.polymarket.com/perps/trading.md
+https://docs.polymarket.com/perps/learn-about-trading/architecture.md
+https://docs.polymarket.com/perps/learn-about-trading/fees.md
+https://docs.polymarket.com/perps/learn-about-trading/funding.md
+https://docs.polymarket.com/perps/learn-about-trading/geographic-restrictions.md
+https://docs.polymarket.com/perps/learn-about-trading/index-price.md
+https://docs.polymarket.com/perps/learn-about-trading/liquidation-mechanics.md
+https://docs.polymarket.com/perps/learn-about-trading/margin.md
+https://docs.polymarket.com/perps/learn-about-trading/mark-price.md
+https://docs.polymarket.com/perps/learn-about-trading/market-sessions.md
+https://docs.polymarket.com/perps/learn-about-trading/markets.md
+https://docs.polymarket.com/perps/learn-about-trading/overview.md
+
+## NEW - Perps WebSocket (2026-07-13)
+https://docs.polymarket.com/api-reference/wss/perps-auth.md
+https://docs.polymarket.com/api-reference/wss/perps-auto-cancel.md
+https://docs.polymarket.com/api-reference/wss/perps-balances.md
+https://docs.polymarket.com/api-reference/wss/perps-bbo.md
+https://docs.polymarket.com/api-reference/wss/perps-book.md
+https://docs.polymarket.com/api-reference/wss/perps-cancel-orders.md
+https://docs.polymarket.com/api-reference/wss/perps-cancel-orders-coid.md
+https://docs.polymarket.com/api-reference/wss/perps-deposits.md
+https://docs.polymarket.com/api-reference/wss/perps-fills.md
+https://docs.polymarket.com/api-reference/wss/perps-funding.md
+https://docs.polymarket.com/api-reference/wss/perps-klines.md
+https://docs.polymarket.com/api-reference/wss/perps-orders.md
+https://docs.polymarket.com/api-reference/wss/perps-ping.md
+https://docs.polymarket.com/api-reference/wss/perps-place-orders.md
+https://docs.polymarket.com/api-reference/wss/perps-portfolio.md
+https://docs.polymarket.com/api-reference/wss/perps-statistics.md
+https://docs.polymarket.com/api-reference/wss/perps-tickers.md
+https://docs.polymarket.com/api-reference/wss/perps-trades.md
+https://docs.polymarket.com/api-reference/wss/perps-update-leverage.md
+https://docs.polymarket.com/api-reference/wss/perps-withdrawals.md
+
+## NEW - Account & Trading API (2026-07-13)
+https://docs.polymarket.com/api-reference/apply-referral-code.md
+https://docs.polymarket.com/api-reference/cancel-orders.md
+https://docs.polymarket.com/api-reference/cancel-orders-coid.md
+https://docs.polymarket.com/api-reference/check-invite-code.md
+https://docs.polymarket.com/api-reference/create-account-invite.md
+https://docs.polymarket.com/api-reference/create-orders.md
+https://docs.polymarket.com/api-reference/create-proxy.md
+https://docs.polymarket.com/api-reference/delete-proxy.md
+https://docs.polymarket.com/api-reference/get-account-limits.md
+https://docs.polymarket.com/api-reference/get-account-referral.md
+https://docs.polymarket.com/api-reference/get-account-rewards.md
+https://docs.polymarket.com/api-reference/get-account-stats.md
+https://docs.polymarket.com/api-reference/get-auto-cancel-status.md
+https://docs.polymarket.com/api-reference/get-balances.md
+https://docs.polymarket.com/api-reference/get-bbo.md
+https://docs.polymarket.com/api-reference/get-book.md
+https://docs.polymarket.com/api-reference/get-collateral-assets.md
+https://docs.polymarket.com/api-reference/get-credentials.md
+https://docs.polymarket.com/api-reference/get-deposits.md
+https://docs.polymarket.com/api-reference/get-equity.md
+https://docs.polymarket.com/api-reference/get-exchange-info.md
+https://docs.polymarket.com/api-reference/get-fees.md
+https://docs.polymarket.com/api-reference/get-fills.md
+https://docs.polymarket.com/api-reference/get-funding-charges.md
+https://docs.polymarket.com/api-reference/get-historical-funding.md
+https://docs.polymarket.com/api-reference/get-index.md
+https://docs.polymarket.com/api-reference/get-instrument-config.md
+https://docs.polymarket.com/api-reference/get-instruments.md
+https://docs.polymarket.com/api-reference/get-internal-transfers.md
+https://docs.polymarket.com/api-reference/get-klines.md
+https://docs.polymarket.com/api-reference/get-limit-tiers.md
+https://docs.polymarket.com/api-reference/get-open-orders.md
+https://docs.polymarket.com/api-reference/get-orders.md
+https://docs.polymarket.com/api-reference/get-pnl.md
+https://docs.polymarket.com/api-reference/get-portfolio.md
+https://docs.polymarket.com/api-reference/get-public-portfolio.md
+https://docs.polymarket.com/api-reference/get-recent-trades.md
+https://docs.polymarket.com/api-reference/get-server-time.md
+https://docs.polymarket.com/api-reference/get-statistics.md
+https://docs.polymarket.com/api-reference/get-tickers.md
+https://docs.polymarket.com/api-reference/get-withdrawals.md
+https://docs.polymarket.com/api-reference/internal-transfer.md
+https://docs.polymarket.com/api-reference/set-auto-cancel.md
+https://docs.polymarket.com/api-reference/test-connection.md
+https://docs.polymarket.com/api-reference/update-leverage.md
+https://docs.polymarket.com/api-reference/withdraw.md
diff --git a/docs/api-reference/apply-referral-code.md b/docs/api-reference/apply-referral-code.md
new file mode 100644
index 0000000..6abaeb4
--- /dev/null
+++ b/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.
+
+
+Request Weight: **1**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/cancel-orders-coid.md b/docs/api-reference/cancel-orders-coid.md
new file mode 100644
index 0000000..077ae15
--- /dev/null
+++ b/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).
+
+
+Request Weight: **1 + floor(n / 20)** Action Weight: **0**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/cancel-orders.md b/docs/api-reference/cancel-orders.md
new file mode 100644
index 0000000..8922897
--- /dev/null
+++ b/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).
+
+
+Request Weight: **1 + floor(n / 20)** Action Weight: **0**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/check-invite-code.md b/docs/api-reference/check-invite-code.md
new file mode 100644
index 0000000..9b6e619
--- /dev/null
+++ b/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.
+
+
+Request Weight: **1**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/create-account-invite.md b/docs/api-reference/create-account-invite.md
new file mode 100644
index 0000000..49ed06a
--- /dev/null
+++ b/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.
+
+
+Request Weight: **1**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/create-orders.md b/docs/api-reference/create-orders.md
new file mode 100644
index 0000000..7c2fd4c
--- /dev/null
+++ b/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).
+
+
+Request Weight: **1 + floor(n / 20)** Action Weight: **1 / order**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/create-proxy.md b/docs/api-reference/create-proxy.md
new file mode 100644
index 0000000..a327027
--- /dev/null
+++ b/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).
+
+
+Request Weight: **1**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/delete-proxy.md b/docs/api-reference/delete-proxy.md
new file mode 100644
index 0000000..b6caa38
--- /dev/null
+++ b/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).
+
+
+Request Weight: **1**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-account-limits.md b/docs/api-reference/get-account-limits.md
new file mode 100644
index 0000000..f48086c
--- /dev/null
+++ b/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.
+
+
+Request Weight: **2**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-account-referral.md b/docs/api-reference/get-account-referral.md
new file mode 100644
index 0000000..f4bf745
--- /dev/null
+++ b/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.
+
+
+Request Weight: **1**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-account-rewards.md b/docs/api-reference/get-account-rewards.md
new file mode 100644
index 0000000..2327cc0
--- /dev/null
+++ b/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.
+
+
+Request Weight: **2**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-account-stats.md b/docs/api-reference/get-account-stats.md
new file mode 100644
index 0000000..5c840e5
--- /dev/null
+++ b/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.
+
+
+Request Weight: **2**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-auto-cancel-status.md b/docs/api-reference/get-auto-cancel-status.md
new file mode 100644
index 0000000..4c19601
--- /dev/null
+++ b/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.
+
+
+Request Weight: **1**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-balances.md b/docs/api-reference/get-balances.md
new file mode 100644
index 0000000..3c7730a
--- /dev/null
+++ b/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.
+
+Request Weight: **2**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-bbo.md b/docs/api-reference/get-bbo.md
new file mode 100644
index 0000000..59bbf95
--- /dev/null
+++ b/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.
+
+Request Weight: **2**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-book.md b/docs/api-reference/get-book.md
new file mode 100644
index 0000000..7734972
--- /dev/null
+++ b/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.
+
+Request Weight:
+
+
+
+Depth 10: **2**
+
+
+
+Depth 100: **5**
+
+
+
+Depth 500: **10**
+
+
+
+Depth 1000: **20**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-collateral-assets.md b/docs/api-reference/get-collateral-assets.md
new file mode 100644
index 0000000..6afb9ab
--- /dev/null
+++ b/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.
+
+
+Request Weight: **2**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-credentials.md b/docs/api-reference/get-credentials.md
new file mode 100644
index 0000000..5c30ec5
--- /dev/null
+++ b/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.
+
+Request Weight: **2**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-deposits.md b/docs/api-reference/get-deposits.md
new file mode 100644
index 0000000..4a700bf
--- /dev/null
+++ b/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.
+
+
+Request Weight: **10**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-equity.md b/docs/api-reference/get-equity.md
new file mode 100644
index 0000000..66e6fb3
--- /dev/null
+++ b/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.
+
+
+Request Weight: **10**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-exchange-info.md b/docs/api-reference/get-exchange-info.md
new file mode 100644
index 0000000..109d3dc
--- /dev/null
+++ b/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.
+
+
+Request Weight: **2**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-fees.md b/docs/api-reference/get-fees.md
new file mode 100644
index 0000000..b5e4e20
--- /dev/null
+++ b/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.
+
+Request Weight: **2**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-fills.md b/docs/api-reference/get-fills.md
new file mode 100644
index 0000000..5f5fad9
--- /dev/null
+++ b/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.
+
+
+Request Weight: **10**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-funding-charges.md b/docs/api-reference/get-funding-charges.md
new file mode 100644
index 0000000..566eeec
--- /dev/null
+++ b/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.
+
+
+Request Weight: **10**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-historical-funding.md b/docs/api-reference/get-historical-funding.md
new file mode 100644
index 0000000..a6ee0bc
--- /dev/null
+++ b/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.
+
+
+Request Weight: **10**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-index.md b/docs/api-reference/get-index.md
new file mode 100644
index 0000000..fbea083
--- /dev/null
+++ b/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.
+
+Request Weight: **2**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-instrument-config.md b/docs/api-reference/get-instrument-config.md
new file mode 100644
index 0000000..c6cac46
--- /dev/null
+++ b/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.
+
+Request Weight: **2**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-instruments.md b/docs/api-reference/get-instruments.md
new file mode 100644
index 0000000..02662a9
--- /dev/null
+++ b/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.
+
+Request Weight: **2**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-internal-transfers.md b/docs/api-reference/get-internal-transfers.md
new file mode 100644
index 0000000..2d967ae
--- /dev/null
+++ b/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.
+
+
+Request Weight: **10**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-klines.md b/docs/api-reference/get-klines.md
new file mode 100644
index 0000000..343a9b6
--- /dev/null
+++ b/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.
+
+
+Request Weight: **5**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-limit-tiers.md b/docs/api-reference/get-limit-tiers.md
new file mode 100644
index 0000000..a90655d
--- /dev/null
+++ b/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.
+
+Request Weight: **2**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-open-orders.md b/docs/api-reference/get-open-orders.md
new file mode 100644
index 0000000..3160927
--- /dev/null
+++ b/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.
+
+Request Weight:
+
+
+
+With instrument ID: **1**
+
+
+
+Without instrument ID: **20**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-orders.md b/docs/api-reference/get-orders.md
new file mode 100644
index 0000000..e02d4c0
--- /dev/null
+++ b/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.
+
+
+Request Weight:
+
+
+
+With order ID: **1**
+
+
+
+Without order ID: **10**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-pnl.md b/docs/api-reference/get-pnl.md
new file mode 100644
index 0000000..0d2dab3
--- /dev/null
+++ b/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.
+
+
+Request Weight: **10**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-portfolio.md b/docs/api-reference/get-portfolio.md
new file mode 100644
index 0000000..1558fc9
--- /dev/null
+++ b/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.
+
+
+Request Weight: **2**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-public-portfolio.md b/docs/api-reference/get-public-portfolio.md
new file mode 100644
index 0000000..bed1da3
--- /dev/null
+++ b/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.
+
+
+Request Weight: **5**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-recent-trades.md b/docs/api-reference/get-recent-trades.md
new file mode 100644
index 0000000..737a2ea
--- /dev/null
+++ b/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.
+
+
+Request Weight: **10**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-server-time.md b/docs/api-reference/get-server-time.md
new file mode 100644
index 0000000..9bd604b
--- /dev/null
+++ b/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.
+
+
+Request Weight: **1**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-statistics.md b/docs/api-reference/get-statistics.md
new file mode 100644
index 0000000..0377284
--- /dev/null
+++ b/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.
+
+Request Weight: **2**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-tickers.md b/docs/api-reference/get-tickers.md
new file mode 100644
index 0000000..56213db
--- /dev/null
+++ b/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.
+
+Request Weight: **2**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/get-withdrawals.md b/docs/api-reference/get-withdrawals.md
new file mode 100644
index 0000000..75d6657
--- /dev/null
+++ b/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.
+
+
+Request Weight: **10**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/internal-transfer.md b/docs/api-reference/internal-transfer.md
new file mode 100644
index 0000000..4b0580b
--- /dev/null
+++ b/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.
+
+
+Request Weight: **1**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/set-auto-cancel.md b/docs/api-reference/set-auto-cancel.md
new file mode 100644
index 0000000..b6f08b2
--- /dev/null
+++ b/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).
+
+
+Request Weight: **1** Action Weight: **10**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/test-connection.md b/docs/api-reference/test-connection.md
new file mode 100644
index 0000000..a94604f
--- /dev/null
+++ b/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.
+
+
+Request Weight: **1**
+
+
+## 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
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/update-leverage.md b/docs/api-reference/update-leverage.md
new file mode 100644
index 0000000..16063b5
--- /dev/null
+++ b/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).
+
+
+Request Weight: **1** Action Weight: **1**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/withdraw.md b/docs/api-reference/withdraw.md
new file mode 100644
index 0000000..a0cda59
--- /dev/null
+++ b/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.
+
+
+Request Weight: **1**
+
+
+## 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'
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/wss/perps-auth.md b/docs/api-reference/wss/perps-auth.md
new file mode 100644
index 0000000..cdedcd2
--- /dev/null
+++ b/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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ op:
+ type: object
+ required:
+ - type
+ - args
+ properties:
+ type:
+ type: string
+ enum:
+ - auth
+ x-parser-schema-id:
+ args:
+ type: object
+ required:
+ - proxy
+ - secret
+ properties:
+ proxy:
+ type: string
+ description: Proxy address in hex format
+ example: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'
+ x-parser-schema-id:
+ secret:
+ type: string
+ description: API secret
+ example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+ x-parser-schema-id:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - req
+ - op
+ x-parser-schema-id:
+ 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:
+ data:
+ oneOf:
+ - type: object
+ required:
+ - status
+ properties:
+ status:
+ type: string
+ enum:
+ - ok
+ x-parser-schema-id:
+ x-parser-schema-id:
+ - type: object
+ required:
+ - status
+ - error
+ properties:
+ status:
+ type: string
+ enum:
+ - err
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - data
+ x-parser-schema-id:
+ title: Auth Response
+ description: Authentication result
+ example: |-
+ {
+ "id": 123,
+ "data": {
+ "status": "",
+ "error": ""
+ }
+ }
+ 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: []
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/wss/perps-auto-cancel.md b/docs/api-reference/wss/perps-auto-cancel.md
new file mode 100644
index 0000000..a380148
--- /dev/null
+++ b/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).
+
+ Action Weight: **10**
+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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ op:
+ type: object
+ required:
+ - type
+ - args
+ properties:
+ type:
+ type: string
+ enum:
+ - autoCancel
+ x-parser-schema-id:
+ args:
+ type: object
+ required:
+ - time
+ properties:
+ time:
+ type: integer
+ description: Timestamp in milliseconds
+ example: 1767225600000
+ x-parser-schema-id:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ sig:
+ type: string
+ description: Signature in hex format
+ example: 0x1234567890...
+ x-parser-schema-id:
+ salt:
+ type: integer
+ description: Salt
+ example: 1234567890
+ x-parser-schema-id:
+ 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:
+ required:
+ - req
+ - op
+ - sig
+ - salt
+ - ts
+ x-parser-schema-id:
+ 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:
+ data:
+ oneOf:
+ - type: object
+ required:
+ - status
+ properties:
+ status:
+ type: string
+ enum:
+ - ok
+ x-parser-schema-id:
+ x-parser-schema-id:
+ - type: object
+ required:
+ - status
+ - error
+ properties:
+ status:
+ type: string
+ enum:
+ - err
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - data
+ x-parser-schema-id:
+ 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: []
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/wss/perps-balances.md b/docs/api-reference/wss/perps-balances.md
new file mode 100644
index 0000000..95b5a91
--- /dev/null
+++ b/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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ chs:
+ type: array
+ description: 'Balances private channel: "balances"'
+ items:
+ type: string
+ enum:
+ - balances
+ x-parser-schema-id:
+ example:
+ - balances
+ x-parser-schema-id:
+ required:
+ - req
+ - chs
+ x-parser-schema-id:
+ 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:
+ data:
+ title: Subscribe Response
+ type: array
+ items:
+ oneOf:
+ - type: object
+ required:
+ - status
+ properties:
+ status:
+ type: string
+ enum:
+ - ok
+ x-parser-schema-id:
+ x-parser-schema-id:
+ - type: object
+ required:
+ - status
+ - error
+ properties:
+ status:
+ type: string
+ enum:
+ - err
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - data
+ x-parser-schema-id:
+ 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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ chs:
+ type: array
+ description: 'Balances private channel: "balances"'
+ items:
+ type: string
+ enum:
+ - balances
+ x-parser-schema-id:
+ example:
+ - balances
+ x-parser-schema-id:
+ required:
+ - req
+ - chs
+ x-parser-schema-id:
+ 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:
+ data:
+ title: Subscribe Response
+ type: array
+ items:
+ oneOf:
+ - type: object
+ required:
+ - status
+ properties:
+ status:
+ type: string
+ enum:
+ - ok
+ x-parser-schema-id:
+ x-parser-schema-id:
+ - type: object
+ required:
+ - status
+ - error
+ properties:
+ status:
+ type: string
+ enum:
+ - err
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - data
+ x-parser-schema-id:
+ 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:
+ 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:
+ sq:
+ type: integer
+ description: Sequence number
+ example: 1234567890
+ x-parser-schema-id:
+ data:
+ type: object
+ description: Balance object
+ properties:
+ asset:
+ type: string
+ description: Asset name
+ example: USDC
+ x-parser-schema-id:
+ balance:
+ type: string
+ description: Total balance
+ example: '10000.00'
+ x-parser-schema-id:
+ value:
+ type: string
+ description: USD value
+ example: '10000.00'
+ x-parser-schema-id:
+ required:
+ - asset
+ - balance
+ - value
+ x-parser-schema-id:
+ required:
+ - ch
+ - ts
+ - sq
+ - data
+ x-parser-schema-id:
+ 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: []
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/wss/perps-bbo.md b/docs/api-reference/wss/perps-bbo.md
new file mode 100644
index 0000000..52221e9
--- /dev/null
+++ b/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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ chs:
+ type: array
+ description: |
+ BBO subscription per instrument: `bbo::{iid}` (e.g. `bbo::1`).
+ items:
+ type: string
+ pattern: ^bbo::\d+$
+ x-parser-schema-id:
+ example:
+ - bbo::1
+ x-parser-schema-id:
+ required:
+ - req
+ - chs
+ x-parser-schema-id:
+ 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:
+ data:
+ title: Subscribe Response
+ type: array
+ items:
+ oneOf:
+ - type: object
+ required:
+ - status
+ properties:
+ status:
+ type: string
+ enum:
+ - ok
+ x-parser-schema-id:
+ x-parser-schema-id:
+ - type: object
+ required:
+ - status
+ - error
+ properties:
+ status:
+ type: string
+ enum:
+ - err
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - data
+ x-parser-schema-id:
+ 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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ chs:
+ type: array
+ description: |
+ BBO subscription per instrument: `bbo::{iid}` (e.g. `bbo::1`).
+ items:
+ type: string
+ pattern: ^bbo::\d+$
+ x-parser-schema-id:
+ example:
+ - bbo::1
+ x-parser-schema-id:
+ required:
+ - req
+ - chs
+ x-parser-schema-id:
+ 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:
+ data:
+ title: Subscribe Response
+ type: array
+ items:
+ oneOf:
+ - type: object
+ required:
+ - status
+ properties:
+ status:
+ type: string
+ enum:
+ - ok
+ x-parser-schema-id:
+ x-parser-schema-id:
+ - type: object
+ required:
+ - status
+ - error
+ properties:
+ status:
+ type: string
+ enum:
+ - err
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - data
+ x-parser-schema-id:
+ 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:
+ 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:
+ sq:
+ type: integer
+ description: Sequence number
+ example: 1234567890
+ x-parser-schema-id:
+ data:
+ type: object
+ description: BBO object
+ title: BBO Data
+ properties:
+ iid:
+ type: integer
+ description: Instrument ID
+ example: 1
+ x-parser-schema-id:
+ bp:
+ type: string
+ description: Best bid price
+ example: '99.50'
+ x-parser-schema-id:
+ bq:
+ type: string
+ description: Best bid quantity
+ example: '10.00'
+ x-parser-schema-id:
+ ap:
+ type: string
+ description: Best ask price
+ example: '100.50'
+ x-parser-schema-id:
+ aq:
+ type: string
+ description: Best ask quantity
+ example: '10.00'
+ x-parser-schema-id:
+ required:
+ - iid
+ - bp
+ - bq
+ - ap
+ - aq
+ x-parser-schema-id:
+ required:
+ - ch
+ - ts
+ - sq
+ - data
+ x-parser-schema-id:
+ 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: []
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/wss/perps-book.md b/docs/api-reference/wss/perps-book.md
new file mode 100644
index 0000000..9388051
--- /dev/null
+++ b/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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ chs:
+ type: array
+ description: Book subscription in format "book::{iid}" (e.g., "book::1")
+ items:
+ type: string
+ pattern: ^book::\d+$
+ x-parser-schema-id:
+ example:
+ - book::1
+ x-parser-schema-id:
+ required:
+ - req
+ - chs
+ x-parser-schema-id:
+ 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:
+ data:
+ title: Subscribe Response
+ type: array
+ items:
+ oneOf:
+ - type: object
+ required:
+ - status
+ properties:
+ status:
+ type: string
+ enum:
+ - ok
+ x-parser-schema-id:
+ x-parser-schema-id:
+ - type: object
+ required:
+ - status
+ - error
+ properties:
+ status:
+ type: string
+ enum:
+ - err
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - data
+ x-parser-schema-id:
+ 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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ chs:
+ type: array
+ description: Book subscription in format "book::{iid}" (e.g., "book::1")
+ items:
+ type: string
+ pattern: ^book::\d+$
+ x-parser-schema-id:
+ example:
+ - book::1
+ x-parser-schema-id:
+ required:
+ - req
+ - chs
+ x-parser-schema-id:
+ 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:
+ data:
+ title: Subscribe Response
+ type: array
+ items:
+ oneOf:
+ - type: object
+ required:
+ - status
+ properties:
+ status:
+ type: string
+ enum:
+ - ok
+ x-parser-schema-id:
+ x-parser-schema-id:
+ - type: object
+ required:
+ - status
+ - error
+ properties:
+ status:
+ type: string
+ enum:
+ - err
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - data
+ x-parser-schema-id:
+ 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:
+ 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:
+ sq:
+ type: integer
+ description: Sequence number
+ example: 1234567890
+ x-parser-schema-id:
+ data:
+ type: object
+ required:
+ - b
+ - a
+ properties:
+ b:
+ type: array
+ items:
+ type: array
+ items:
+ type: string
+ x-parser-schema-id:
+ maxItems: 2
+ description: |
+ - `"100.00"` - Price
+ - `"10.00"` - Quantity
+ example:
+ - '100.00'
+ - '10.00'
+ x-parser-schema-id:
+ description: Bid levels
+ x-parser-schema-id:
+ a:
+ type: array
+ items:
+ type: array
+ items:
+ type: string
+ x-parser-schema-id:
+ maxItems: 2
+ description: |
+ - `"100.00"` - Price
+ - `"10.00"` - Quantity
+ example:
+ - '100.00'
+ - '10.00'
+ x-parser-schema-id:
+ description: Ask levels
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - ch
+ - ts
+ - sq
+ - data
+ x-parser-schema-id:
+ 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: []
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/wss/perps-cancel-orders-coid.md b/docs/api-reference/wss/perps-cancel-orders-coid.md
new file mode 100644
index 0000000..542d303
--- /dev/null
+++ b/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).
+
+ Action Weight: **0**
+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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ op:
+ type: object
+ required:
+ - type
+ - args
+ properties:
+ type:
+ type: string
+ enum:
+ - cancelOrdersCOID
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ sig:
+ type: string
+ description: Signature in hex format
+ example: 0x1234567890...
+ x-parser-schema-id:
+ salt:
+ type: integer
+ description: Salt
+ example: 1234567890
+ x-parser-schema-id:
+ 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:
+ 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:
+ required:
+ - req
+ - op
+ - sig
+ - salt
+ - ts
+ x-parser-schema-id:
+ 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:
+ 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:
+ oid:
+ type: integer
+ description: Order ID
+ example: 1234567890
+ x-parser-schema-id:
+ coid:
+ type: string
+ description: Client order ID
+ minLength: 32
+ maxLength: 32
+ pattern: ^[0-9a-f]{32}$
+ example: 550e8400e29b41d4a716446655440000
+ x-parser-schema-id:
+ x-parser-schema-id:
+ - type: object
+ required:
+ - status
+ - error
+ properties:
+ status:
+ type: string
+ enum:
+ - err
+ x-parser-schema-id:
+ oid:
+ type: integer
+ description: Order ID
+ example: 1234567890
+ x-parser-schema-id:
+ coid:
+ type: string
+ description: Client order ID
+ minLength: 32
+ maxLength: 32
+ pattern: ^[0-9a-f]{32}$
+ example: 550e8400e29b41d4a716446655440000
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - data
+ x-parser-schema-id:
+ 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: []
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/wss/perps-cancel-orders.md b/docs/api-reference/wss/perps-cancel-orders.md
new file mode 100644
index 0000000..2c3aa2e
--- /dev/null
+++ b/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).
+
+ Action Weight: **0**
+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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ op:
+ type: object
+ required:
+ - type
+ - args
+ properties:
+ type:
+ type: string
+ enum:
+ - cancelOrders
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ sig:
+ type: string
+ description: Signature in hex format
+ example: 0x1234567890...
+ x-parser-schema-id:
+ salt:
+ type: integer
+ description: Salt
+ example: 1234567890
+ x-parser-schema-id:
+ 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:
+ 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:
+ required:
+ - req
+ - op
+ - sig
+ - salt
+ - ts
+ x-parser-schema-id:
+ 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:
+ 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:
+ oid:
+ type: integer
+ description: Order ID
+ example: 1234567890
+ x-parser-schema-id:
+ coid:
+ type: string
+ description: Client order ID
+ minLength: 32
+ maxLength: 32
+ pattern: ^[0-9a-f]{32}$
+ example: 550e8400e29b41d4a716446655440000
+ x-parser-schema-id:
+ x-parser-schema-id:
+ - type: object
+ required:
+ - status
+ - error
+ properties:
+ status:
+ type: string
+ enum:
+ - err
+ x-parser-schema-id:
+ oid:
+ type: integer
+ description: Order ID
+ example: 1234567890
+ x-parser-schema-id:
+ coid:
+ type: string
+ description: Client order ID
+ minLength: 32
+ maxLength: 32
+ pattern: ^[0-9a-f]{32}$
+ example: 550e8400e29b41d4a716446655440000
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - data
+ x-parser-schema-id:
+ 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: []
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/wss/perps-deposits.md b/docs/api-reference/wss/perps-deposits.md
new file mode 100644
index 0000000..dc57892
--- /dev/null
+++ b/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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ chs:
+ type: array
+ description: 'Deposits private channel: "deposits"'
+ items:
+ type: string
+ enum:
+ - deposits
+ x-parser-schema-id:
+ example:
+ - deposits
+ x-parser-schema-id:
+ required:
+ - req
+ - chs
+ x-parser-schema-id:
+ 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:
+ data:
+ title: Subscribe Response
+ type: array
+ items:
+ oneOf:
+ - type: object
+ required:
+ - status
+ properties:
+ status:
+ type: string
+ enum:
+ - ok
+ x-parser-schema-id:
+ x-parser-schema-id:
+ - type: object
+ required:
+ - status
+ - error
+ properties:
+ status:
+ type: string
+ enum:
+ - err
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - data
+ x-parser-schema-id:
+ 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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ chs:
+ type: array
+ description: 'Deposits private channel: "deposits"'
+ items:
+ type: string
+ enum:
+ - deposits
+ x-parser-schema-id:
+ example:
+ - deposits
+ x-parser-schema-id:
+ required:
+ - req
+ - chs
+ x-parser-schema-id:
+ 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:
+ data:
+ title: Subscribe Response
+ type: array
+ items:
+ oneOf:
+ - type: object
+ required:
+ - status
+ properties:
+ status:
+ type: string
+ enum:
+ - ok
+ x-parser-schema-id:
+ x-parser-schema-id:
+ - type: object
+ required:
+ - status
+ - error
+ properties:
+ status:
+ type: string
+ enum:
+ - err
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - data
+ x-parser-schema-id:
+ 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:
+ 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:
+ sq:
+ type: integer
+ description: Sequence number
+ example: 1234567890
+ x-parser-schema-id:
+ 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:
+ asset:
+ type: string
+ description: Asset name
+ example: USDC
+ x-parser-schema-id:
+ 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:
+ status:
+ type: string
+ description: Deposit status
+ enum:
+ - pending
+ - confirmed
+ - removed
+ x-parser-schema-id:
+ required:
+ - hash
+ - asset
+ - amount
+ - status
+ x-parser-schema-id:
+ required:
+ - ch
+ - ts
+ - sq
+ - data
+ x-parser-schema-id:
+ 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: []
+
+````
\ No newline at end of file
diff --git a/docs/api-reference/wss/perps-fills.md b/docs/api-reference/wss/perps-fills.md
new file mode 100644
index 0000000..3f1b35e
--- /dev/null
+++ b/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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ chs:
+ type: array
+ description: 'Fills private channel: "fills"'
+ items:
+ type: string
+ enum:
+ - fills
+ x-parser-schema-id:
+ example:
+ - fills
+ x-parser-schema-id:
+ required:
+ - req
+ - chs
+ x-parser-schema-id:
+ 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:
+ data:
+ title: Subscribe Response
+ type: array
+ items:
+ oneOf:
+ - type: object
+ required:
+ - status
+ properties:
+ status:
+ type: string
+ enum:
+ - ok
+ x-parser-schema-id:
+ x-parser-schema-id:
+ - type: object
+ required:
+ - status
+ - error
+ properties:
+ status:
+ type: string
+ enum:
+ - err
+ x-parser-schema-id:
+ 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:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ x-parser-schema-id:
+ required:
+ - data
+ x-parser-schema-id:
+ 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:
+ req:
+ type: string
+ description: Request type
+ enum:
+ - post
+ - sub
+ - unsub
+ x-parser-schema-id:
+ chs:
+ type: array
+ description: 'Fills private channel: "fills"'
+ items:
+ type: string
+ enum:
+ - fills
+ x-parser-schema-id:
+ example:
+ - fills
+ x-parser-schema-id:
+ required:
+ - req
+ - chs
+ x-parser-schema-id:
+ 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: