> ## 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.

# Execution

> Fill a quote, place a direct or limit order, cancel, and redeem

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](/concepts/order-lifecycle).

| 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](/integration-options) compares when to use each.

## Fill a quote

Get an executable quote with the user's token ([Quotes & smart routing](/concepts/quotes)), check
`status` is `ok`, then fill it.

<CodeGroup>
  ```bash cURL theme={null}
  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\" }"
  ```

  ```ts SDK theme={null}
  const fill = await client.executeManaged({ quoteId: quote.quoteId });
  ```
</CodeGroup>

```json theme={null}
{
  "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](/recipes/self-custody). |

API reference: [Execute quote](/api-reference/trading/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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```ts SDK theme={null}
  const order = await client.placeOrder({
    venue: "polymarket",
    venueMarketOutcomeId: "cmf3q8z2m00a4mw0lr5t1k7yc",
    side: "buy",
    maxSpend: 25,
    externalId: "trade-2f9c61d4",
  });
  ```
</CodeGroup>

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](/recipes/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.

```bash theme={null}
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](/recipes/limit-orders).

## Cancel an order

```bash theme={null}
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](/recipes/self-custody).

## 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](/concepts/market-resolution). See [Redeem winnings](/api-reference/trading/redeem-winnings-for-resolved-positions).

## 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](/concepts/errors).