diff --git a/docs/api-reference/core/get-trades-for-a-user-or-markets.md b/docs/api-reference/core/get-trades-for-a-user-or-markets.md index 2db81c4..b22ff2a 100644 --- a/docs/api-reference/core/get-trades-for-a-user-or-markets.md +++ b/docs/api-reference/core/get-trades-for-a-user-or-markets.md @@ -98,6 +98,23 @@ paths: enum: - BUY - SELL + - in: query + name: start + schema: + type: integer + minimum: 0 + description: >- + Lower-bound timestamp (epoch seconds) for the trade window. Omit or + pass `0` for the default window (most recent ~3 years); pass a + positive epoch (e.g. `1`) to retrieve full history. + - in: query + name: end + schema: + type: integer + minimum: 0 + description: >- + Upper-bound timestamp (epoch seconds) for the trade window. Omit for + the default (current time); rows newer than `end` are excluded. responses: '200': description: Success diff --git a/docs/api-reference/core/get-user-activity.md b/docs/api-reference/core/get-user-activity.md index 2a9958b..4001432 100644 --- a/docs/api-reference/core/get-user-activity.md +++ b/docs/api-reference/core/get-user-activity.md @@ -108,6 +108,9 @@ paths: schema: type: integer minimum: 0 + description: >- + Upper-bound timestamp (epoch seconds) for the activity window. Omit + for the default (current time); rows newer than `end` are excluded. - in: query name: sortBy schema: diff --git a/docs/changelog/changelog.md b/docs/changelog/changelog.md index bc579dd..1fce57e 100644 --- a/docs/changelog/changelog.md +++ b/docs/changelog/changelog.md @@ -6,6 +6,12 @@ > Welcome to the Polymarket Changelog. Here you will find any important changes to Polymarket, including but not limited to CLOB, API, UI and Mobile Applications. + + * **Sports fee coefficient**: The sports taker fee rate increases from `0.03` to `0.05` at midnight UTC. + * **Sports maker rebate**: The sports maker rebate decreases from 25% to 15% of collected taker fees. + * **Updated documentation**: [Fees](/trading/fees) and [Maker Rebates Program](/market-makers/maker-rebates). + + * **Finer tick size for World Cup markets**: All World Cup *to advance*, *moneyline*, *spreads*, and *totals* markets are now decimalized to a **0.0025 (0.25¢)** tick size. This lets you execute at smaller ticks and tighter spreads for the most competitive prices. Applies only to those World Cup markets — see [Tick Sizes](/trading/orders/overview#tick-sizes). diff --git a/docs/dev-tooling/python.md b/docs/dev-tooling/python.md index a7e1312..36ed52a 100644 --- a/docs/dev-tooling/python.md +++ b/docs/dev-tooling/python.md @@ -1102,6 +1102,25 @@ Secure clients expose the API credentials created for the authenticated session. ## Changelog +### `0.1.0b17` + +* Added SDK pagination for Combo lifecycle activity and server-cursor pagination for Combo positions. +* Added typed overloads for market, event, and tag lookups, mutually-exclusive lookup arguments, and `redeem_positions`. +* Added trade time filters. +* Hardened Combo pagination filters and branded Combo activity IDs. +* Breaking beta change: Combo activity and position fields now use `wallet`, `amount`, and `payout`; Combo activity rows no longer expose `module_kind`. + +```diff theme={null} +-activity.user_address +-activity.amount_usdc +-redeem_activity.payout_usdc +-position.user_address ++activity.wallet ++activity.amount ++redeem_activity.payout ++position.wallet +``` + ### `0.1.0b16` * Fixed Deposit Wallet trading setup approvals to use the current Protocol V2 auto-redeem operator. diff --git a/docs/dev-tooling/typescript.md b/docs/dev-tooling/typescript.md index 0f44f2d..e8934f8 100644 --- a/docs/dev-tooling/typescript.md +++ b/docs/dev-tooling/typescript.md @@ -1103,6 +1103,24 @@ Secure clients expose the API credentials created for the authenticated session. ## Changelog +### `0.1.0-beta.14` + +* Added SDK pagination for Combo lifecycle activity and server-cursor pagination for Combo positions. +* Added Combo position sync request fields and exposed `outcome` and `redeemable` on Combo positions. +* Branded Combo activity row IDs. +* Breaking beta change: Combo activity and position fields now use `wallet`, `amount`, and `payout`; Combo activity rows no longer expose `moduleKind`. + +```diff theme={null} +-activity.userAddress +-activity.amountUsdc +-redeemActivity.payoutUsdc +-position.userAddress ++activity.wallet ++activity.amount ++redeemActivity.payout ++position.wallet +``` + ### `0.1.0-beta.13` * Added `listMarketClarifications` for reading market clarification text with SDK-owned pagination and market, event, state, question, and transaction filters. diff --git a/docs/developers/CLOB/orders/check-scoring.md b/docs/developers/CLOB/orders/check-scoring.md index e464ba0..2001338 100644 --- a/docs/developers/CLOB/orders/check-scoring.md +++ b/docs/developers/CLOB/orders/check-scoring.md @@ -33,9 +33,10 @@ The underlying order primitive is structured, hashed, and signed using the [EIP- * **GTC** and **GTD** are limit order types — they rest on the book at your specified price. - **GTD expiration**: There is a security threshold of one minute. If you need - the order to expire in 90 seconds, the correct expiration value is `now + 1 - minute + 30 seconds`. + **GTD expiration**: Orders expire one minute before their stated expiration + as a security threshold, and the expiration must be at least three minutes + in the future. For a 5-minute effective lifetime, the correct expiration + value is `now + 1 minute + 5 minutes`. ### Post-Only Orders diff --git a/docs/developers/CLOB/orders/create-order-batch.md b/docs/developers/CLOB/orders/create-order-batch.md index 6041c77..7b25901 100644 --- a/docs/developers/CLOB/orders/create-order-batch.md +++ b/docs/developers/CLOB/orders/create-order-batch.md @@ -208,7 +208,7 @@ GTD orders auto-expire at a specified time. Useful for quoting around known even .size(dec!(10)) .side(Side::Buy) .order_type(OrderType::GTD) - .expiration(Utc::now() + TimeDelta::hours(1)) + .expiration(Utc::now() + TimeDelta::minutes(1) + TimeDelta::hours(1)) .build() .await?; let signed = client.sign(&signer, order).await?; @@ -217,9 +217,11 @@ GTD orders auto-expire at a specified time. Useful for quoting around known even - There is a security threshold of one minute on GTD expiration. To set an - effective lifetime of N seconds, use `now + 60 + N`. For example, for a - 30-second effective lifetime, set the expiration to `now + 60 + 30`. + GTD orders expire one minute before their stated expiration as a security + threshold. To set an effective lifetime of N seconds, use `now + 60 + N`. + In addition, the expiration must be at least three minutes in the future — + orders expiring sooner are rejected — so the minimum effective lifetime is + about two minutes. *** diff --git a/docs/developers/CLOB/orders/create-order.md b/docs/developers/CLOB/orders/create-order.md index 6041c77..7b25901 100644 --- a/docs/developers/CLOB/orders/create-order.md +++ b/docs/developers/CLOB/orders/create-order.md @@ -208,7 +208,7 @@ GTD orders auto-expire at a specified time. Useful for quoting around known even .size(dec!(10)) .side(Side::Buy) .order_type(OrderType::GTD) - .expiration(Utc::now() + TimeDelta::hours(1)) + .expiration(Utc::now() + TimeDelta::minutes(1) + TimeDelta::hours(1)) .build() .await?; let signed = client.sign(&signer, order).await?; @@ -217,9 +217,11 @@ GTD orders auto-expire at a specified time. Useful for quoting around known even - There is a security threshold of one minute on GTD expiration. To set an - effective lifetime of N seconds, use `now + 60 + N`. For example, for a - 30-second effective lifetime, set the expiration to `now + 60 + 30`. + GTD orders expire one minute before their stated expiration as a security + threshold. To set an effective lifetime of N seconds, use `now + 60 + N`. + In addition, the expiration must be at least three minutes in the future — + orders expiring sooner are rejected — so the minimum effective lifetime is + about two minutes. *** diff --git a/docs/developers/CLOB/orders/get-active-order.md b/docs/developers/CLOB/orders/get-active-order.md index e464ba0..2001338 100644 --- a/docs/developers/CLOB/orders/get-active-order.md +++ b/docs/developers/CLOB/orders/get-active-order.md @@ -33,9 +33,10 @@ The underlying order primitive is structured, hashed, and signed using the [EIP- * **GTC** and **GTD** are limit order types — they rest on the book at your specified price. - **GTD expiration**: There is a security threshold of one minute. If you need - the order to expire in 90 seconds, the correct expiration value is `now + 1 - minute + 30 seconds`. + **GTD expiration**: Orders expire one minute before their stated expiration + as a security threshold, and the expiration must be at least three minutes + in the future. For a 5-minute effective lifetime, the correct expiration + value is `now + 1 minute + 5 minutes`. ### Post-Only Orders diff --git a/docs/developers/CLOB/orders/get-order.md b/docs/developers/CLOB/orders/get-order.md index e464ba0..2001338 100644 --- a/docs/developers/CLOB/orders/get-order.md +++ b/docs/developers/CLOB/orders/get-order.md @@ -33,9 +33,10 @@ The underlying order primitive is structured, hashed, and signed using the [EIP- * **GTC** and **GTD** are limit order types — they rest on the book at your specified price. - **GTD expiration**: There is a security threshold of one minute. If you need - the order to expire in 90 seconds, the correct expiration value is `now + 1 - minute + 30 seconds`. + **GTD expiration**: Orders expire one minute before their stated expiration + as a security threshold, and the expiration must be at least three minutes + in the future. For a 5-minute effective lifetime, the correct expiration + value is `now + 1 minute + 5 minutes`. ### Post-Only Orders diff --git a/docs/developers/CLOB/orders/onchain-order-info.md b/docs/developers/CLOB/orders/onchain-order-info.md index e464ba0..2001338 100644 --- a/docs/developers/CLOB/orders/onchain-order-info.md +++ b/docs/developers/CLOB/orders/onchain-order-info.md @@ -33,9 +33,10 @@ The underlying order primitive is structured, hashed, and signed using the [EIP- * **GTC** and **GTD** are limit order types — they rest on the book at your specified price. - **GTD expiration**: There is a security threshold of one minute. If you need - the order to expire in 90 seconds, the correct expiration value is `now + 1 - minute + 30 seconds`. + **GTD expiration**: Orders expire one minute before their stated expiration + as a security threshold, and the expiration must be at least three minutes + in the future. For a 5-minute effective lifetime, the correct expiration + value is `now + 1 minute + 5 minutes`. ### Post-Only Orders diff --git a/docs/developers/CLOB/orders/orders.md b/docs/developers/CLOB/orders/orders.md index e464ba0..2001338 100644 --- a/docs/developers/CLOB/orders/orders.md +++ b/docs/developers/CLOB/orders/orders.md @@ -33,9 +33,10 @@ The underlying order primitive is structured, hashed, and signed using the [EIP- * **GTC** and **GTD** are limit order types — they rest on the book at your specified price. - **GTD expiration**: There is a security threshold of one minute. If you need - the order to expire in 90 seconds, the correct expiration value is `now + 1 - minute + 30 seconds`. + **GTD expiration**: Orders expire one minute before their stated expiration + as a security threshold, and the expiration must be at least three minutes + in the future. For a 5-minute effective lifetime, the correct expiration + value is `now + 1 minute + 5 minutes`. ### Post-Only Orders diff --git a/docs/developers/CLOB/status.md b/docs/developers/CLOB/status.md index 8af0fbb..6ead301 100644 --- a/docs/developers/CLOB/status.md +++ b/docs/developers/CLOB/status.md @@ -1,4 +1,4 @@ -Polymarket - StatusPolymarket - Status

Polymarket - Status Page

All systems operational

Website - Operational

100% - uptime
Notice history 90 days ago

CLOB API - Operational

100% - uptime
Notice history 90 days ago

Markets API - Operational

100% - uptime
Notice history 90 days ago

Polygon (RPC) - Operational

100% - uptime
Notice history 90 days ago

User auth - Operational

100% - uptime
Notice history 90 days ago

Sports API - Operational

100% - uptime
Notice history 90 days ago

Recent notices

Show notice history

Polymarket - Status Page

All systems operational

Website - Operational

100% - uptime
Notice history 90 days ago

CLOB API - Operational

100% - uptime
Notice history 90 days ago

Markets API - Operational

100% - uptime
Notice history 90 days ago

Polygon (RPC) - Operational

100% - uptime
Notice history 90 days ago

User auth - Operational

100% - uptime
Notice history 90 days ago

Sports API - Operational

100% - uptime
Notice history 90 days ago

Recent notices

Show notice history
\ No newline at end of file +
\ No newline at end of file diff --git a/docs/market-makers/combos.md b/docs/market-makers/combos.md index dc6243a..0a7fa6a 100644 --- a/docs/market-makers/combos.md +++ b/docs/market-makers/combos.md @@ -1623,8 +1623,8 @@ form](https://forms.gle/dk5A1DRw8EN5uP9z5). Makers are expected to accept most selected quotes. We track acceptance rates, - and makers who reject more than 15% of selected quotes over a one-hour lookback - window may be paused from quoting for a few minutes. + and makers who reject more than 15% of selected quotes over a one-hour + lookback window may be paused from quoting for a few minutes. Once access is enabled, your quoting system will immediately be asked to review @@ -1886,11 +1886,14 @@ fresh outside the quote path. Use `client.listComboPositions(...)` to page through Combo positions for the - authenticated account. Filter by status, Combo condition ID, or Combo position - ID when you only need a subset of positions. + authenticated account. ```ts theme={null} - import { ComboPositionStatus, type ComboPosition } from "@polymarket/client"; + import { + ComboPositionSort, + ComboPositionStatus, + type ComboPosition, + } from "@polymarket/client"; const positions = client.listComboPositions({ status: ComboPositionStatus.Open, @@ -1904,6 +1907,31 @@ fresh outside the quote path. } ``` + You can filter positions by the following criteria. `conditionId` accepts one + Combo condition ID or an array of Combo condition IDs. + + + ```ts Condition ID theme={null} + const positions = client.listComboPositions({ + conditionId: ["", ""], + }); + ``` + + ```ts Status theme={null} + const positions = client.listComboPositions({ + status: ComboPositionStatus.Open, + }); + ``` + + ```ts Incremental Sync theme={null} + const positions = client.listComboPositions({ + updatedAfter: lastWatermarkSeconds, + sort: ComboPositionSort.UpdatedAsc, + pageSize: 1000, + }); + ``` + + Each returned item is a `ComboPosition`. @@ -1911,14 +1939,19 @@ fresh outside the quote path. type ComboPosition = { conditionId: ComboConditionId; positionId: PositionId; + outcome: ComboPositionOutcome; moduleId: number; - userAddress: Address; + wallet: Address; shares: DecimalString; entryAvgPriceUsdc?: DecimalString | null; entryCostUsdc?: DecimalString | null; + realizedPayoutUsdc?: DecimalString | null; + totalCostUsdc?: DecimalString | null; status: ComboPositionStatus; + redeemable: boolean; firstEntryAt: IsoDateTimeString; resolvedAt?: IsoDateTimeString | null; + updatedAt?: IsoDateTimeString; legsTotal: number; legsResolved: number; legsPending: number; @@ -1966,27 +1999,10 @@ fresh outside the quote path. ``` - You can filter positions by the following criteria: - - - ```ts Condition ID theme={null} - const positions = client.listComboPositions({ - conditionId: "", - }); - ``` - - ```ts Position ID theme={null} - const positions = client.listComboPositions({ - positionId: "", - }); - ``` - - ```ts Status theme={null} - const positions = client.listComboPositions({ - status: ComboPositionStatus.Open, - }); - ``` - + For redeemed positions, `shares` and `entryCostUsdc` track remaining inventory, + so both can read as zero after a winning Combo is redeemed. Use + `realizedPayoutUsdc` for gross redemption proceeds and `totalCostUsdc` for + original cost basis; net result is `realizedPayoutUsdc - totalCostUsdc`. @@ -2003,6 +2019,31 @@ fresh outside the quote path. ... ``` + You can filter positions by the following criteria. `condition_id` accepts one + Combo condition ID or a sequence of Combo condition IDs. + + + ```python Condition ID theme={null} + positions = client.list_combo_positions( + condition_id=["", ""], + ) + ``` + + ```python Status theme={null} + positions = client.list_combo_positions( + status="OPEN", + ) + ``` + + ```python Incremental Sync theme={null} + positions = client.list_combo_positions( + updated_after=last_watermark_seconds, + sort="updated_asc", + page_size=1000, + ) + ``` + + The returned `ComboPosition` models include the following fields: @@ -2010,14 +2051,19 @@ fresh outside the quote path. class ComboPosition: condition_id: ComboConditionId position_id: PositionId + outcome: ComboPositionOutcome module_id: int - user_address: EvmAddress + wallet: EvmAddress shares: Decimal entry_avg_price_usdc: Decimal | None entry_cost_usdc: Decimal | None + realized_payout_usdc: Decimal | None + total_cost_usdc: Decimal | None status: ComboPositionStatus + redeemable: bool first_entry_at: datetime resolved_at: datetime | None + updated_at: datetime | None legs_total: int legs_resolved: int legs_pending: int @@ -2061,27 +2107,10 @@ fresh outside the quote path. ``` - You can filter positions by the following criteria: - - - ```python Condition ID theme={null} - positions = client.list_combo_positions( - condition_id="", - ) - ``` - - ```python Position ID theme={null} - positions = client.list_combo_positions( - position_id="", - ) - ``` - - ```python Status theme={null} - positions = client.list_combo_positions( - status="OPEN", - ) - ``` - + For redeemed positions, `shares` and `entry_cost_usdc` track remaining + inventory, so both can be zero after a winning Combo is redeemed. Use + `realized_payout_usdc` for gross redemption proceeds and `total_cost_usdc` for + original cost basis; net result is `realized_payout_usdc - total_cost_usdc`. @@ -2100,7 +2129,7 @@ fresh outside the quote path. ```bash Condition ID theme={null} curl -G "https://data-api.polymarket.com/v1/positions/combos" \ --data-urlencode "user=" \ - --data-urlencode "combo_condition_id=" + --data-urlencode "market_id=" ``` ```bash Position ID theme={null} @@ -2135,6 +2164,7 @@ fresh outside the quote path. "status": "OPEN", "first_entry_at": "2026-06-08T00:00:00Z", "resolved_at": null, + "updated_at": "2026-06-08T00:00:00Z", "legs_total": 2, "legs_resolved": 0, "legs_pending": 2, @@ -2155,27 +2185,441 @@ fresh outside the quote path. "pagination": { "limit": 50, "offset": 0, - "has_more": false, - "next_cursor": null + "has_more": true, + "next_cursor": "eyJsIjo1MCwibyI6NTB9" } } ``` + + Use `cursor` from `pagination.next_cursor` to fetch the next page. Keep the same + filters and `sort`; `cursor` supersedes `offset`. A `null` cursor means there + are no more pages. + + ```bash Cursor theme={null} + curl -G "https://data-api.polymarket.com/v1/positions/combos" \ + --data-urlencode "user=" \ + --data-urlencode "limit=100" \ + --data-urlencode "sort=first_entry_desc" \ + --data-urlencode "cursor=" + ``` + + Use `updatedAfter` with `sort=updated_asc` to incrementally sync changed + positions. Store the newest `updated_at` you process as your next watermark; + boundary rows may re-deliver, so upsert by `(combo_condition_id, + combo_position_id)`. + + ```bash Incremental sync theme={null} + curl -G "https://data-api.polymarket.com/v1/positions/combos" \ + --data-urlencode "user=" \ + --data-urlencode "updatedAfter=" \ + --data-urlencode "sort=updated_asc" \ + --data-urlencode "limit=1000" + ``` + + For redeemed positions, `shares_balance` and `entry_cost_usdc` track remaining + inventory, so both can read as zero after a winning Combo is redeemed. Use + `realized_payout_usdc` for gross redemption proceeds and `total_cost_usdc` for + original cost basis; net result is `realized_payout_usdc - total_cost_usdc`. - - **Displaying closed (redeemed) positions.** `entry_cost_usdc` is the - *remaining* cost basis (`entry_avg_price × shares_balance`), so it reads `~0` - once a winning combo is redeemed — and `shares_balance` does too. Two fields - carry the closed-position economics instead: +### List Combo Activity - * `realized_payout_usdc` — gross redemption proceeds (winning shares redeem - 1:1 at \$1; accumulates under `PARTIAL`) - * `total_cost_usdc` — original cost basis, reconstructed as - `entry_avg_price × (shares_balance + realized_payout)` +Use Combo activity when you need an audit trail for inventory-changing events, +including splits, merges, conversions, wraps, unwraps, and redeems. Use Combo +positions for current inventory state. - Net result of a finished combo = `realized_payout_usdc − total_cost_usdc`. - + + + Use `client.listComboActivity(...)` to page through Combo lifecycle activity for + the authenticated account. + + ```ts theme={null} + import { ComboActivityType, type ComboActivity } from "@polymarket/client"; + + const activity = client.listComboActivity({ pageSize: 50 }); + + for await (const page of activity) { + for (const item of page.items) { + // item: ComboActivity + if (item.type === ComboActivityType.Redeem) { + console.log(item.positionId, item.payout); + } + } + } + ``` + + Filter to one or more Combos with `conditionId`. + + ```ts theme={null} + const activity = client.listComboActivity({ + conditionId: ["", ""], + }); + ``` + + Each returned item is a discriminated `ComboActivity` union. All lifecycle rows + share the base fields; redeem rows also include the redeemed position ID and + payout. + + + ```ts ComboActivity theme={null} + type ComboActivity = + | ComboSplitActivity + | ComboMergeActivity + | ComboConvertActivity + | ComboCompressActivity + | ComboWrapActivity + | ComboUnwrapActivity + | ComboRedeemActivity; + ``` + + ```ts Split / Merge theme={null} + type ComboSplitActivity = { + id: ComboActivityId; + type: ComboActivityType.Split; + wallet: Address; + conditionId: ComboConditionId; + moduleId: number; + amount: DecimalString | null; + timestamp: EpochMilliseconds; + transactionAt: IsoDateTimeString; + transactionHash: TxHash; + logIndex: number; + blockNumber: number; + legs: ComboPositionLeg[]; + }; + + type ComboMergeActivity = { + id: ComboActivityId; + type: ComboActivityType.Merge; + wallet: Address; + conditionId: ComboConditionId; + moduleId: number; + amount: DecimalString | null; + timestamp: EpochMilliseconds; + transactionAt: IsoDateTimeString; + transactionHash: TxHash; + logIndex: number; + blockNumber: number; + legs: ComboPositionLeg[]; + }; + ``` + + ```ts Convert / Compress theme={null} + type ComboConvertActivity = { + id: ComboActivityId; + type: ComboActivityType.Convert; + wallet: Address; + conditionId: ComboConditionId; + moduleId: number; + amount: DecimalString | null; + timestamp: EpochMilliseconds; + transactionAt: IsoDateTimeString; + transactionHash: TxHash; + logIndex: number; + blockNumber: number; + legs: ComboPositionLeg[]; + }; + + type ComboCompressActivity = { + id: ComboActivityId; + type: ComboActivityType.Compress; + wallet: Address; + conditionId: ComboConditionId; + moduleId: number; + amount: DecimalString | null; + timestamp: EpochMilliseconds; + transactionAt: IsoDateTimeString; + transactionHash: TxHash; + logIndex: number; + blockNumber: number; + legs: ComboPositionLeg[]; + }; + ``` + + ```ts Wrap / Unwrap theme={null} + type ComboWrapActivity = { + id: ComboActivityId; + type: ComboActivityType.Wrap; + wallet: Address; + conditionId: ComboConditionId; + moduleId: number; + amount: DecimalString | null; + timestamp: EpochMilliseconds; + transactionAt: IsoDateTimeString; + transactionHash: TxHash; + logIndex: number; + blockNumber: number; + legs: ComboPositionLeg[]; + }; + + type ComboUnwrapActivity = { + id: ComboActivityId; + type: ComboActivityType.Unwrap; + wallet: Address; + conditionId: ComboConditionId; + moduleId: number; + amount: DecimalString | null; + timestamp: EpochMilliseconds; + transactionAt: IsoDateTimeString; + transactionHash: TxHash; + logIndex: number; + blockNumber: number; + legs: ComboPositionLeg[]; + }; + ``` + + ```ts ComboRedeemActivity theme={null} + type ComboRedeemActivity = { + id: ComboActivityId; + type: ComboActivityType.Redeem; + wallet: Address; + conditionId: ComboConditionId; + moduleId: number; + amount: DecimalString | null; + timestamp: EpochMilliseconds; + transactionAt: IsoDateTimeString; + transactionHash: TxHash; + logIndex: number; + blockNumber: number; + legs: ComboPositionLeg[]; + positionId: PositionId; + payout: DecimalString | null; + }; + ``` + + + + + Use `client.list_combo_activity(...)` to page through Combo lifecycle activity + for a wallet. + + ```python theme={null} + activity = client.list_combo_activity( + user="", + page_size=50, + ) + + for page in activity: + for item in page.items: + # item: ComboActivity + if item.type == "REDEEM": + print(item.position_id, item.payout) + ``` + + Filter to one or more Combos with `condition_id`. + + ```python theme={null} + activity = client.list_combo_activity( + user="", + condition_id=["", ""], + ) + ``` + + The returned `ComboActivity` models use a `type` discriminator. All lifecycle + rows share the base fields; redeem rows also include the redeemed position ID + and payout. + + + ```python ComboActivity theme={null} + ComboActivity = ( + ComboSplitActivity + | ComboMergeActivity + | ComboConvertActivity + | ComboCompressActivity + | ComboWrapActivity + | ComboUnwrapActivity + | ComboRedeemActivity + ) + ``` + + ```python Split / Merge theme={null} + class ComboSplitActivity: + id: ComboActivityId + type: Literal["SPLIT"] + wallet: EvmAddress + condition_id: ComboConditionId + module_id: int + amount: Decimal | None + timestamp: datetime + transaction_at: datetime + transaction_hash: TransactionHash + log_index: int + block_number: int + legs: tuple[ComboPositionLeg, ...] + + + class ComboMergeActivity: + id: ComboActivityId + type: Literal["MERGE"] + wallet: EvmAddress + condition_id: ComboConditionId + module_id: int + amount: Decimal | None + timestamp: datetime + transaction_at: datetime + transaction_hash: TransactionHash + log_index: int + block_number: int + legs: tuple[ComboPositionLeg, ...] + ``` + + ```python Convert / Compress theme={null} + class ComboConvertActivity: + id: ComboActivityId + type: Literal["CONVERT"] + wallet: EvmAddress + condition_id: ComboConditionId + module_id: int + amount: Decimal | None + timestamp: datetime + transaction_at: datetime + transaction_hash: TransactionHash + log_index: int + block_number: int + legs: tuple[ComboPositionLeg, ...] + + + class ComboCompressActivity: + id: ComboActivityId + type: Literal["COMPRESS"] + wallet: EvmAddress + condition_id: ComboConditionId + module_id: int + amount: Decimal | None + timestamp: datetime + transaction_at: datetime + transaction_hash: TransactionHash + log_index: int + block_number: int + legs: tuple[ComboPositionLeg, ...] + ``` + + ```python Wrap / Unwrap theme={null} + class ComboWrapActivity: + id: ComboActivityId + type: Literal["WRAP"] + wallet: EvmAddress + condition_id: ComboConditionId + module_id: int + amount: Decimal | None + timestamp: datetime + transaction_at: datetime + transaction_hash: TransactionHash + log_index: int + block_number: int + legs: tuple[ComboPositionLeg, ...] + + + class ComboUnwrapActivity: + id: ComboActivityId + type: Literal["UNWRAP"] + wallet: EvmAddress + condition_id: ComboConditionId + module_id: int + amount: Decimal | None + timestamp: datetime + transaction_at: datetime + transaction_hash: TransactionHash + log_index: int + block_number: int + legs: tuple[ComboPositionLeg, ...] + ``` + + ```python ComboRedeemActivity theme={null} + class ComboRedeemActivity: + id: ComboActivityId + type: Literal["REDEEM"] + wallet: EvmAddress + condition_id: ComboConditionId + module_id: int + amount: Decimal | None + timestamp: datetime + transaction_at: datetime + transaction_hash: TransactionHash + log_index: int + block_number: int + legs: tuple[ComboPositionLeg, ...] + position_id: PositionId + payout: Decimal | None + ``` + + + + + Use the Data API to list Combo lifecycle activity for a wallet. + + ```bash theme={null} + curl -G "https://data-api.polymarket.com/v1/activity/combos" \ + --data-urlencode "user=" \ + --data-urlencode "limit=50" + ``` + + Filter to specific Combos with `market_id`, which accepts comma-separated + `combo_condition_id` values. + + ```bash Filter by Combo theme={null} + curl -G "https://data-api.polymarket.com/v1/activity/combos" \ + --data-urlencode "user=" \ + --data-urlencode "market_id=," + ``` + + The response returns lifecycle events in `activity` and pagination metadata in + `pagination`. + + ```json theme={null} + { + "activity": [ + { + "id": "-", + "event_kind": "PositionsSplit", + "side": "Split", + "module_kind": "Combinatorial", + "user_address": "", + "combo_condition_id": "", + "combo_position_id": "", + "module_id": 3, + "amount_usdc": 10.0, + "payout_usdc": null, + "timestamp": 1783379945, + "tx_dttm": "2026-07-06T23:19:05Z", + "tx_hash": "", + "log_index": 2409, + "block_number": 89783300, + "legs": [ + { + "leg_index": 0, + "leg_position_id": "", + "leg_condition_id": "", + "leg_outcome_index": 0, + "leg_outcome_label": "Yes", + "leg_status": "OPEN", + "leg_resolved_at": null, + "leg_current_price": "0.52" + } + ] + } + ], + "pagination": { + "limit": 50, + "offset": 0, + "has_more": true, + "next_cursor": "eyJsIjo1MCwibyI6NTB9" + } + } + ``` + + Use `cursor` from `pagination.next_cursor` to fetch the next page. `cursor` + supersedes `offset`. A `null` cursor means there are no more pages. + + ```bash Cursor theme={null} + curl -G "https://data-api.polymarket.com/v1/activity/combos" \ + --data-urlencode "user=" \ + --data-urlencode "limit=50" \ + --data-urlencode "cursor=" + ``` + + ### Inventory Management diff --git a/docs/market-makers/maker-rebates.md b/docs/market-makers/maker-rebates.md index 3d77a60..0b06b09 100644 --- a/docs/market-makers/maker-rebates.md +++ b/docs/market-makers/maker-rebates.md @@ -38,7 +38,7 @@ Maker Rebates are funded by taker fees collected in eligible markets. A percenta | Category | Maker Rebate | Distribution Method | | --------------- | ------------ | ------------------- | | Crypto | 20% | Fee-curve weighted | -| Sports | 25% | Fee-curve weighted | +| Sports | 15% | Fee-curve weighted | | Finance | 25% | Fee-curve weighted | | Politics | 25% | Fee-curve weighted | | Economics | 25% | Fee-curve weighted | @@ -72,7 +72,7 @@ Where **C** = number of shares traded and **p** = price of the shares. The fee p | Category | Taker Fee Rate | Maker Fee Rate | | --------------- | -------------- | -------------- | | Crypto | 0.07 | 0 | -| Sports | 0.03 | 0 | +| Sports | 0.05 | 0 | | Finance | 0.04 | 0 | | Politics | 0.04 | 0 | | Economics | 0.05 | 0 | @@ -99,7 +99,7 @@ Taker fees are calculated in pUSD and vary based on the share price. The fee amo
-