> ## Documentation Index > Fetch the complete documentation index at: https://docs.agg.market/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To integrate AGG, start with Quickstart: REST (https://docs.agg.market/quickstart/rest), then Order lifecycle & statuses (https://docs.agg.market/concepts/order-lifecycle). > Track every trade until it reaches a terminal status. Before retrying a failed or timed-out call, read Errors, retries & idempotency (https://docs.agg.market/concepts/errors). > The API reference is generated from https://docs.agg.market/openapi/openapi.json. # Place an order directly > Places a market order on a single named venue without a prior quote. The route is priced and funded server-side and always produces exactly one order. `externalId` is required and unique within your app — two different users of the same app cannot share one — so retrying a timed-out request with the same value returns 409 instead of trading twice. ## OpenAPI ````yaml /openapi/openapi.json post /execution/orders openapi: 3.0.2 info: title: AGG API version: 1.0.0 description: >- Prediction market aggregator REST API — authentication, users, venue events, venue markets, orderbooks, charts, and execution workflows. servers: - url: https://api.agg.market description: Production security: [] tags: - name: Authentication description: Sign users in and manage their session tokens. - name: Markets description: Find events, markets and outcomes to trade. - name: Market Data description: Live orderbooks, prices, charts and scores for those markets. - name: Trading description: Quote, place, sign, track and cancel orders. - name: Portfolio description: A user's orders, positions, balances and activity. - name: Funding description: Deposit addresses, withdrawals, balance refills and fiat on-ramp. - name: Users description: The signed-in user's profile, linked accounts, KYC and venue keys. - name: Hosted Venue Accounts description: Provision, fund and withdraw from venue accounts hosted for the user. - name: Webhooks description: Configure and operate webhook delivery to your server. - name: Partner Admin description: Server-side reads across your app's users, orders and analytics. - name: Paper Trading description: Simulated accounts and orders for testing without real funds. - name: News description: News feeds linked to markets. - name: Correlated Markets description: Markets related to a given market and the effect of its resolution. paths: /execution/orders: post: tags: - Trading summary: Place an order directly description: >- Places a market order on a single named venue without a prior quote. The route is priced and funded server-side and always produces exactly one order. `externalId` is required and unique within your app — two different users of the same app cannot share one — so retrying a timed-out request with the same value returns 409 instead of trading twice. operationId: placeOrder requestBody: required: true content: application/json: schema: additionalProperties: false type: object required: - venue - venueMarketOutcomeId - side - externalId properties: venue: allOf: - $ref: '#/components/schemas/Venue' description: >- The venue to trade on. Singular by design — this endpoint never splits an order. venueMarketOutcomeId: minLength: 1 description: >- The outcome to trade. May be the outcome on another venue: it is resolved through matched-outcome links to the equivalent outcome on `venue`. Passing the id that already lives on `venue` is the unambiguous form. type: string side: description: >- Trade direction. `sell` closes an existing position on `venue`. type: string enum: - buy - sell maxSpend: exclusiveMinimum: true description: Buy only. Maximum all-in USD spend, inclusive of app fee. type: number minimum: 0 sellShares: exclusiveMinimum: true description: Sell only. Number of contracts to sell. type: number minimum: 0 externalId: minLength: 1 maxLength: 36 description: >- Idempotency key. Your own id for this trade — required, and unique within your app: two different users of the same app cannot share one. A repeat is rejected with 409 rather than trading twice, so it is safe to retry a request that timed out using the same value. type: string slipCapBps: minimum: 0 description: >- Slippage cap in basis points. Defaults to 500 (5%) when omitted. On sells set this explicitly: `sellShares` bounds the shares sold, not the proceeds. type: number allowedSourceChainIds: minItems: 1 description: >- Restrict funding to these source chains. Omitted, the order may be funded from any chain the user holds, bridging in when the venue's own chain is short. Listing only the venue's chain (56 for predict.fun, 137 for Polymarket) makes the order fail with insufficient funding instead of bridging. Balances are still read on-chain: this narrows which of them may be spent, it never adds capacity. type: array items: minimum: 1 type: integer chainBalances: description: >- Per-chain USD funding budgets, e.g. `{"56": 50}`. Caps refreshed wallet balances; never adds capacity. A chain-only budget is shared across its token buckets. Omitted chains cannot fund the order; an empty map allows no on-chain funding. Combines with `allowedSourceChainIds`: excluded chains cannot fund the order. type: object additionalProperties: minimum: 0 type: number appFeeBips: minimum: 0 maximum: 10000 multipleOf: 1 description: >- Per-trade app fee in basis points of routed notional, 0..10000. Replaces the app's configured rate for this order only. Honoured only when the request carries x-app-api-key; otherwise 400 app_fee_override_requires_api_key. Buy only. type: number referrer: minLength: 42 maxLength: 42 description: >- Referral: the EVM address that receives the referral fee. Requires referrerFeeBips. Honoured only when the request carries x-app-api-key; a JWT-only request that sends it is rejected with 400 referral_requires_api_key. Buy only. type: string referrerFeeBips: minimum: 1 maximum: 10000 multipleOf: 1 description: >- Referral fee in basis points of the routed notional, 1..10000. AGG takes no share of it. With referralPayer "user" it is reserved from maxSpend next to the app fee; with "app" the user pays nothing. type: number referralPayer: description: Who funds the referral. Default "user". type: string enum: - user - app referralPayerAddress: minLength: 42 maxLength: 42 description: >- Required when referralPayer is "app": the wallet that settles the payout. After the fill, a pendingSignatures entry appears with signerAddress set to this address and purpose "referral_payout"; answer it on POST /execution/fill/:quoteId/signatures. Read its type: on an EVM chain it is a `transaction` to broadcast (post the hash), on HyperCore an `eip712` to sign (post the signature). type: string referralPayoutChainId: minimum: 1 multipleOf: 1 description: >- Optional, and only with referralPayer "app": the chain the referrer is paid on. Must carry USDC. On an EVM chain the payout is an ERC-20 transfer the partner's wallet broadcasts, needing USDC plus native gas there; on HyperCore (1337) it is a user-signed sendAsset from the partner's HyperCore spot balance — a signature, nothing to broadcast — and the referrer receives spot USDC on Hyperliquid. A first payout to a referrer with no Hyperliquid account costs the partner an extra 1 USDC that Hyperliquid charges to create it; later payouts to the same referrer cost nothing. Solana does not support app-paid payouts and is refused. Defaults to the trade's fee chain, or Polygon when that chain is not EVM. Sending it with a user-paid referral is rejected with 400 referral_invalid. type: number skipQuote: description: >- Skip the smart-route solver and send one order straight to `venue`. predict, hyperliquid, novig and prophetx only; any other venue returns 400. Requires a `read_write` `x-app-api-key` (401 without a key, 403 with a `read` key). No bridging: the funds must already sit on the venue's own chain, and `allowedSourceChainIds` / `chainBalances` are ignored. Referral fields are rejected with 400. You own the price and minimum checks — an order the venue refuses fails after acceptance and uses up its `externalId`. type: boolean skipBalance: description: >- With `skipQuote`, skip the balance check and fund hold on a buy: nothing checks the balance and an underfunded order fails at the venue. Sells still check and hold the position. Without `skipQuote`, skip only the quote-time balance refresh: the route uses the last stored balances, and the fund hold and balance check still run, so a stale balance can fail the order after acceptance but never overspend. Requires a `read_write` `x-app-api-key`. type: boolean price: exclusiveMinimum: true exclusiveMaximum: true description: >- With `skipQuote`, the price to trade at, e.g. `0.52`. Optional: omitted, the best available price at submission is used (best ask for a buy, best bid for a sell), and an empty side returns 400. A hyperliquid buy is sized as the whole contracts that fit `maxSpend` at this price plus slippage. Ignored on prophetx, which prices the order itself within `slipCapBps`. type: number minimum: 0 maximum: 1 example: venue: polymarket venueMarketOutcomeId: cmf3q8z2m00a4mw0lr5t1k7yc side: buy maxSpend: 25 externalId: trade-2f9c61d4 slipCapBps: 200 responses: '200': description: '200' content: application/json: schema: type: object required: - orderId - externalId - venue - status - quoteId - quotedPriceRaw - quotedCostRaw - quotedSharesRaw properties: orderId: description: The single order this call created. type: string externalId: description: >- Echoed back so a webhook or socket event can be tied to this response. type: string venue: allOf: - $ref: '#/components/schemas/Venue' description: The venue the order was placed on. status: description: >- Always `pending`: the order is accepted and queued for execution, not yet filled. Poll `GET /execution/orders` or listen for order events for the terminal state. type: string enum: - pending quoteId: description: >- Server-minted quote backing this order. Useful for support, not required. type: string quotedPriceRaw: description: >- Quoted price, decimal string (e.g. "0.53"). `null` if the order row does not carry a quoted price — the order is still live; re-fetch it from `GET /execution/orders` rather than treating this as zero. type: string nullable: true quotedCostRaw: description: >- Quoted cost, 6-decimal atomic USDC. `null` under the same conditions as `quotedPriceRaw`. type: string nullable: true quotedSharesRaw: description: >- Quoted shares, 6-decimal atomic. `null` under the same conditions as `quotedPriceRaw`. type: string nullable: true example: orderId: cmf3r1a2b00c4mw0lq8y7e3uj externalId: trade-2f9c61d4 venue: polymarket status: pending quoteId: k2r8v5n1x7c4m9t3b6q0w2za quotedPriceRaw: '0.52' quotedCostRaw: '25000000' quotedSharesRaw: '48076923' '400': description: '400' content: application/json: schema: $ref: '#/components/schemas/QuoteError' '401': description: '401' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '403': description: '403' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '404': description: '404' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '409': description: '409' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' security: - appId: [] bearerAuth: [] components: schemas: Venue: type: string enum: - kalshi - polymarket - limitless - opinion - predict - pred - tiprun - probable - myriad - hyperliquid - novig - prophetx - betdex QuoteError: type: object required: - message properties: message: type: string code: type: string enum: - quote_not_found - quote_expired - quote_already_executed - quote_cancelled - quote_user_mismatch - quote_app_blocked - quote_unfillable - quote_min_order_size - quote_stale_status - quote_stale_price - quote_insufficient_balance - quote_market_inactive - quote_self_custody_unsupported_venue - quote_self_custody_app_fee - quote_self_custody_redeem_unsupported - venue_not_executable - outcome_ambiguous ErrorMessage: type: object required: - message properties: message: type: string securitySchemes: appId: type: apiKey in: header name: x-app-id description: Your application ID. Required for all app-tier and user-tier routes. bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT access token returned by POST /auth/verify. Required for user-tier routes. ````