> For the complete documentation index, see [llms.txt](https://docs.bullpen.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bullpen.fi/prediction-markets/polymarket-integration.md). # Polymarket Integration All prediction market trades on Bullpen execute through Polymarket's hybrid-decentralized orderbook on Polygon. ## What is Polymarket? Polymarket is a prediction market protocol built on Polygon. It operates a hybrid-decentralized Central Limit Order Book (CLOB) where order matching happens off-chain while settlement and execution occur on-chain. The system has three core components: * **CLOB Operator**: Handles order matching and book management off-chain * **Exchange Contract**: Executes matched trades on-chain via atomic swaps * **Conditional Token Framework (CTF)**: Gnosis-based ERC1155 tokens representing market outcomes Bullpen routes prediction market orders to Polymarket's CLOB. ## How Orders Execute 1. You place an order through Bullpen 2. Order is signed with your wallet (EIP-712 structured data) 3. Submitted to Polymarket's CLOB operator 4. Operator matches your order against resting liquidity 5. Matched orders are submitted to the Exchange contract on Polygon 6. Trade settles on-chain, tokens transfer to your proxy wallet Order matching is off-chain for speed. Settlement is on-chain for security and custody. ## Order Book Mechanics Polymarket uses **price-time priority** with a unified orderbook: 1. Best prices execute first 2. At the same price, oldest orders fill first 3. Yes and No orders match against each other on a single book The unified book means a Yes buy at $0.60 can match against a No buy at $0.40. When their prices sum to $1.00, the operator creates new outcome tokens from collateral and distributes them. ## Order Matching Types Orders can match in three ways: | Match Type | Description | | ---------- | ----------------------------------------------------------------- | | **Fill** | Your order matches against an existing resting order | | **Mint** | Two opposing orders (Yes + No) summing to $1.00 create new tokens | | **Merge** | Two sell orders (Yes + No) burn tokens and release collateral | ## Supported Order Types Polymarket supports limit orders as the base primitive. Market orders are simulated by using marketable limit prices. | Order Type | Behavior | | ---------- | --------------------------------------------------------------- | | **GTC** | Good-Til-Cancelled. Rests on the book until filled or cancelled | | **FOK** | Fill-Or-Kill. Must fill entirely and immediately, or cancel | | **GTD** | Good-Til-Date. Expires at a specified timestamp | See [Order Types](/prediction-markets/order-types.md) for details on each. ## Margin and Collateral Prediction markets on Polymarket do not use leverage. All positions are fully collateralized. When you place an order: 1. Your available USDC.e balance is checked 2. The order amount is reserved against your balance 3. You cannot place additional orders exceeding your remaining balance Example: With 500 USDC.e, you can place one order to buy 1,000 Yes shares at $0.50. Any additional orders in that market will be rejected until the first order fills or is cancelled. ## Price Display Prices shown on Polymarket represent the **midpoint** of the bid-ask spread, unless the spread exceeds $0.10. In wide-spread markets, the last traded price is displayed instead. The orderbook displays: * **Bid**: Highest price someone will pay * **Ask**: Lowest price someone will sell * **Spread**: Difference between bid and ask * **Depth**: Total volume at each price level ## Fees Polymarket charges a taker fee on certain markets. These fees fund Polymarket's [Maker Rebates Program](https://docs.polymarket.com/market-makers/maker-rebates), which redistributes fees daily to market makers to incentivize deeper liquidity and tighter spreads. **Makers are never charged fees.** Only takers pay fees. **Geopolitical markets are fee-free.** There are no Polymarket fees to deposit, withdraw, or redeem USDC ### Fee Formula ``` fee = C × feeRate × p × (1 - p) ``` Where **C** = number of shares traded and **p** = price of the shares. The effective rate peaks at 50% probability and decreases symmetrically toward $0.00 and $1.00. #### Fee Structure by Category | Category | Taker Fee Rate | Maker Fee Rate | Maker Rebate | | --------------- | -------------- | -------------- | ------------ | | Crypto | 0.072 | 0 | 20% | | Sports | 0.03 | 0 | 25% | | Finance | 0.04 | 0 | 25% | | Politics | 0.04 | 0 | 25% | | Economics | 0.05 | 0 | 25% | | Culture | 0.05 | 0 | 25% | | Weather | 0.05 | 0 | 25% | | Other / General | 0.05 | 0 | 25% | | Mentions | 0.04 | 0 | 25% | | Tech | 0.04 | 0 | 25% | | Geopolitics | 0 | 0 | — | See [Polymarket's Fees Documentation](https://docs.polymarket.com/trading/fees) for the latest information. ## Conditional Tokens Outcome shares are ERC-1155 tokens built on the Gnosis Conditional Token Framework (CTF). Each market has: * A **condition ID** identifying the market * Two **position IDs** for Yes and No outcomes * **Collateral** backing the tokens (USDC.e) Full details in [Positions and Settlement](/prediction-markets/positions-and-settlement.md). ## Multi-Outcome Markets Some markets have more than two outcomes (e.g., "Who will win the election?" with multiple candidates). These use the **NegRiskAdapter** contract: * Each candidate gets their own Yes/No binary market * Exactly one candidate's Yes resolves to $1.00 * All other candidates' Yes tokens resolve to $0.00 * No tokens can be converted across markets for capital efficiency ## Sports Markets Sports markets have special rules: * All outstanding limit orders are automatically cancelled when the game begins * The orderbook is cleared at the official start time * Only positions held at game start remain active ## Key Polymarket Resources For deeper technical details: * [Polymarket Docs: CLOB Introduction](https://docs.polymarket.com/developers/CLOB/introduction) * [Order Types](https://docs.polymarket.com/developers/CLOB/orders/orders) * [Conditional Token Framework](https://docs.polymarket.com/developers/CTF/merge) * [Proxy Wallets](https://docs.polymarket.com/developers/proxy-wallet) * [NegRisk Adapter](https://docs.polymarket.com/developers/neg-risk/overview) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.bullpen.fi/prediction-markets/polymarket-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.