Execution

Every trading call is user-tier: send x-app-id and the user’s Authorization: Bearer token. Every call returns before the trade finishes. Track it to a final state with Order lifecycle & statuses.

Call	What it does	Track with
`POST /execution/fill`	Executes a quote, possibly split across venues	`GET /execution/status?quoteId=`
`POST /execution/orders`	Market order on one named venue, no prior quote	`GET /execution/status?quoteId=` or `GET /execution/orders?externalId=`
`POST /execution/limit-orders`	Resting order at your price on one venue	`GET /execution/orders?orderId=`
`POST /execution/orders/cancel`	Cancels an order	`GET /execution/orders?orderId=`
`POST /execution/redeem`	Claims winnings on resolved positions	Redeem events on the WebSocket

Choose your integration compares when to use each.

Fill a quote

Get an executable quote with the user’s token (Quotes & smart routing), check status is ok, then fill it.

curl -X POST https://api.agg.market/execution/fill \
  -H "x-app-id: $AGG_APP_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d "{ \"quoteId\": \"$QUOTE_ID\" }"

const fill = await client.executeManaged({ quoteId: quote.quoteId });

{
  "quoteId": "k2r8v5n1x7c4m9t3b6q0w2za",
  "orderIds": ["cmf3r1a2b00c4mw0lq8y7e3uj", "cmf3r1a3c00c5mw0lt2k9w6nd"],
  "status": "pending"
}

status is always pending: the trade is accepted, not done. orderIds has one order per venue leg. Poll GET /execution/status?quoteId= until terminal is true. Optional body fields:

Field	Use
`mode`	`paper` to fill a paper quote. Must match the quote’s mode.
`fallbackToLatest`	`{ outcomeId, side, maxSpend \| sellShares, allowedVenues? }`. If the quote expired, fill the user’s latest quote with the same intent.
`signingAddress`, `fundingAddresses`, `approveMode`	Self-custody. See Self-custody trading.

API reference: Execute quote.

Place a direct order

POST /execution/orders places a market order on one venue you name. It never splits, and AGG prices and funds it server-side. externalId is required and makes retries safe.

curl -X POST https://api.agg.market/execution/orders \
  -H "x-app-id: $AGG_APP_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "venue": "polymarket",
    "venueMarketOutcomeId": "cmf3q8z2m00a4mw0lr5t1k7yc",
    "side": "buy",
    "maxSpend": 25,
    "externalId": "trade-2f9c61d4"
  }'

const order = await client.placeOrder({
  venue: "polymarket",
  venueMarketOutcomeId: "cmf3q8z2m00a4mw0lr5t1k7yc",
  side: "buy",
  maxSpend: 25,
  externalId: "trade-2f9c61d4",
});

The response has orderId, externalId, status: "pending", and a quoteId you can poll. On a buy, maxSpend is the all-in ceiling including your app fee. slipCapBps defaults to 500 (5%); set it explicitly on sells. Live only: there is no paper mode. Details, including skipQuote for server integrations: Direct order execution.

Place a limit order

POST /execution/limit-orders rests an order at your price on one venue. Prices and sizes are 6-decimal integer strings: limitPriceRaw: "450000" is $0.45, sizeRaw: "20000000" is 20 shares.

curl -X POST https://api.agg.market/execution/limit-orders \
  -H "x-app-id: $AGG_APP_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "venue": "polymarket",
    "venueMarketOutcomeId": "cmf3q8z2m00a4mw0lr5t1k7yc",
    "side": "buy",
    "limitPriceRaw": "450000",
    "sizeRaw": "20000000",
    "timeInForce": "GTC",
    "clientOrderId": "limit-7f3a2c"
  }'

timeInForce is one of GTC, GTD (with expiresAt), FOK, FAK, IOC, or ALO. Venues support different subsets. A managed buy reserves cash (reservedCostRaw); a sell reserves shares. The order starts pending, then becomes open when it rests on the venue. open is not final. Details: Limit orders.

Cancel an order

curl -X POST https://api.agg.market/execution/orders/cancel \
  -H "x-app-id: $AGG_APP_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "orderId": "cmf3r1a2b00c4mw0lq8y7e3uj" }'

The response is { quoteId, orderIds, status }. status can be cancel_pending while the venue confirms. Keep polling the order. A filled or already cancelled order returns 409. Self-custody orders need a fresh cancelSignature from the signing wallet. SDK: client.cancelManagedOrder.

Self-custody

In self-custody the user’s own wallet funds the trade and signs it. You still quote and fill, but add signingAddress, then answer the signature requests that appear on the status endpoint. See Self-custody trading.

Redeem winnings

When a market resolves, POST /execution/redeem claims the user’s payout and credits USDC. Some venues settle on their own and need no redeem call, and a split or voided market pays less than $1 a share. See Market resolution & voids. See Redeem winnings.

Checks at fill time

AGG checks these again when you fill, so a quote that looked fine can still be refused:

The user’s location against each venue in the route. A blocked venue returns 403.
Your app’s venue and category settings. Returns 400 quote_app_blocked.
The market is still open. Returns 400 quote_market_inactive.
The user’s balance still covers the trade. Returns 400 quote_insufficient_balance.
Testing-mode trade cap. Returns 403.

Codes and retry rules: Errors, retries & idempotency.

Start here

Core concepts

SDK reference

Account & identity

Trading guides

Market data & discovery

Security & compliance

Real-time

Webhooks

UI Kit

Releases

Fill a quote

Place a direct order

Place a limit order

Cancel an order

Self-custody

Redeem winnings

Checks at fill time

​Fill a quote

​Place a direct order

​Place a limit order

​Cancel an order

​Self-custody

​Redeem winnings

​Checks at fill time

Fill a quote

Place a direct order

Place a limit order

Cancel an order

Self-custody

Redeem winnings

Checks at fill time