> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairos.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Private Block Trade Auctions on the Kairos Agora API

> Use the Kairos Agora Auction House API to create private auctions, invite market makers, collect firm quotes, and execute institutional block trades.

Agora is the Kairos private auction house for institutional block trades. When you need to move a large position without signaling to the open market, Agora lets you run a sealed, invitation-only auction: you specify the contract and size, invite selected market makers, collect firm executable quotes, and settle against the best price — all through a structured API flow.

<Info>
  All Agora API calls require a first-party session JWT: `Authorization: Bearer <jwt>`. Contact the Kairos team to enable Agora access on your account. Base URL: `https://agora.kairos.trade`.
</Info>

***

## How an auction works

A typical Agora auction runs through four phases:

<Steps>
  <Step title="Originator creates the auction">
    The buy-side principal (originator) opens an auction, specifying the market, side, size, and how long makers have to quote.
  </Step>

  <Step title="Market makers are invited">
    Kairos delivers invitations to the selected makers. Makers see the auction details through the private event stream or the invitation inbox.
  </Step>

  <Step title="Makers submit firm quotes">
    Each invited maker posts a firm, executable price and quantity. They can revise their quote until the auction closes. Quotes are not visible to competing makers.
  </Step>

  <Step title="Originator reviews and settles">
    Before the deadline, the originator inspects the available quotes and either lets the auction settle at best price or cancels.
  </Step>
</Steps>

***

## Step 1 — Run a preflight check

Before creating an auction, verify that you have the collateral capacity to support the trade. This does **not** reserve anything.

```bash theme={null}
curl -X POST "https://agora.kairos.trade/v1/auctions/preflight" \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "polymarket",
    "market_id": "0xabc123",
    "outcome": "YES",
    "side": "buy",
    "size": 10000
  }'
```

```python theme={null}
import os
import httpx

AUTH_HEADERS = {"Authorization": f"Bearer {os.environ['KAIROS_JWT']}"}
MAKER_HEADERS = {"Authorization": f"Bearer {os.environ['KAIROS_MAKER_JWT']}"}

resp = httpx.post(
    "https://agora.kairos.trade/v1/auctions/preflight",
    json={
        "provider": "polymarket",
        "market_id": "0xabc123",
        "outcome": "YES",
        "side": "buy",
        "size": 10000,
    },
    headers=AUTH_HEADERS,
)
print(resp.json())
```

**Example response:**

```json theme={null}
{
  "eligible": true,
  "available_capacity": 50000,
  "required_collateral": 6200,
  "warnings": []
}
```

<Warning>
  If `eligible` is `false`, check the `warnings` array. Common reasons include insufficient collateral, the market being near resolution, or Agora access not being enabled on your account.
</Warning>

***

## Step 2 — Create an auction

When preflight passes, open the auction with `POST /v1/auctions`. Set `expires_in_seconds` to give makers enough time to price the block.

```bash theme={null}
curl -X POST "https://agora.kairos.trade/v1/auctions" \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "polymarket",
    "market_id": "0xabc123",
    "outcome": "YES",
    "side": "buy",
    "size": 10000,
    "expires_in_seconds": 300,
    "invited_makers": ["maker_alpha", "maker_beta", "maker_gamma"],
    "notes": "Looking for YES exposure before the FOMC meeting"
  }'
```

```python theme={null}
resp = httpx.post(
    "https://agora.kairos.trade/v1/auctions",
    json={
        "provider": "polymarket",
        "market_id": "0xabc123",
        "outcome": "YES",
        "side": "buy",
        "size": 10000,
        "expires_in_seconds": 300,
        "invited_makers": ["maker_alpha", "maker_beta", "maker_gamma"],
        "notes": "Looking for YES exposure before the FOMC meeting",
    },
    headers=AUTH_HEADERS,
)
auction = resp.json()
auction_id = auction["auction_id"]
print(f"Auction created: {auction_id}")
```

**Example response:**

```json theme={null}
{
  "auction_id": "auc_7gXp2mNkQwY3",
  "status": "open",
  "provider": "polymarket",
  "market_id": "0xabc123",
  "outcome": "YES",
  "side": "buy",
  "size": 10000,
  "expires_at": "2025-01-15T14:28:05Z",
  "invited_makers": ["maker_alpha", "maker_beta", "maker_gamma"],
  "quote_count": 0,
  "created_at": "2025-01-15T14:23:05Z"
}
```

***

## Step 3 — Monitor the auction (originator)

Poll `GET /v1/auctions/{auctionID}` to see incoming quotes and current status. The response is filtered to show only information your role is permitted to see.

```bash theme={null}
curl "https://agora.kairos.trade/v1/auctions/auc_7gXp2mNkQwY3" \
  -H "Authorization: Bearer $KAIROS_JWT"
```

**Example response (originator view):**

```json theme={null}
{
  "auction_id": "auc_7gXp2mNkQwY3",
  "status": "open",
  "size": 10000,
  "expires_at": "2025-01-15T14:28:05Z",
  "quote_count": 2,
  "best_quote": {
    "price": 0.615,
    "size": 10000,
    "maker": "maker_alpha"
  }
}
```

For a full audit timeline of all events on an auction, use `GET /v1/auctions/{auctionID}/events`.

### List all your auctions

```bash theme={null}
curl "https://agora.kairos.trade/v1/auctions" \
  -H "Authorization: Bearer $KAIROS_JWT"
```

***

## Step 4 — Submit a quote (market maker)

If you are an invited maker, you receive an invitation through the private event stream or your invitation inbox. Submit your firm quote with `POST /v1/auctions/{auctionID}/quotes`.

```bash theme={null}
curl -X POST "https://agora.kairos.trade/v1/auctions/auc_7gXp2mNkQwY3/quotes" \
  -H "Authorization: Bearer $KAIROS_MAKER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 0.615,
    "size": 10000
  }'
```

```python theme={null}
resp = httpx.post(
    f"https://agora.kairos.trade/v1/auctions/{auction_id}/quotes",
    json={"price": 0.615, "size": 10000},
    headers=MAKER_HEADERS,
)
print(resp.json())
```

**Example response:**

```json theme={null}
{
  "quote_id": "qte_3nRa1bWcXzY8",
  "auction_id": "auc_7gXp2mNkQwY3",
  "price": 0.615,
  "size": 10000,
  "status": "active",
  "submitted_at": "2025-01-15T14:25:00Z"
}
```

<Tip>
  You can revise your quote at any time before the auction closes by calling `POST /v1/auctions/{auctionID}/quotes` again with updated parameters. Only one active quote per maker is permitted.
</Tip>

### Check maker capacity before quoting

Before submitting a quote, verify that you have the inventory to back it:

```bash theme={null}
curl -X POST "https://agora.kairos.trade/v1/auctions/auc_7gXp2mNkQwY3/quotes/preflight" \
  -H "Authorization: Bearer $KAIROS_MAKER_JWT" \
  -H "Content-Type: application/json" \
  -d '{"price": 0.615, "size": 10000}'
```

### Withdraw a quote

To pull your quote before the auction closes:

```bash theme={null}
curl -X DELETE "https://agora.kairos.trade/v1/auctions/auc_7gXp2mNkQwY3/quotes" \
  -H "Authorization: Bearer $KAIROS_MAKER_JWT"
```

***

## Cancel an auction

The originator can cancel an open auction at any time before settlement:

```bash theme={null}
curl -X POST "https://agora.kairos.trade/v1/auctions/auc_7gXp2mNkQwY3/cancel" \
  -H "Authorization: Bearer $KAIROS_JWT"
```

**Example response:**

```json theme={null}
{
  "auction_id": "auc_7gXp2mNkQwY3",
  "status": "cancelled",
  "cancelled_at": "2025-01-15T14:26:30Z"
}
```

All invited makers are notified of the cancellation through the event stream.

***

## Check your invitation inbox

As a market maker, check your durable invitation inbox for pending and historical invitations:

```bash theme={null}
curl "https://agora.kairos.trade/v1/invitations" \
  -H "Authorization: Bearer $KAIROS_MAKER_JWT"
```

***

## Real-time auction events via WebSocket

Subscribe to the private Agora event stream to receive real-time notifications without polling. Connect to `GET /v1/stream` with your API key.

```javascript theme={null}
const ws = new WebSocket(
  "wss://agora.kairos.trade/v1/stream?token=" + encodeURIComponent(apiKey)
);

ws.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);

  if (msg.event_type === "auction.invited") {
    console.log(`Invited to auction ${msg.auction_id} — size: ${msg.size}`);
    // Review and call POST /v1/auctions/{auctionID}/quotes
  }

  if (msg.event_type === "auction.quote_received") {
    console.log(`New quote on auction ${msg.auction_id}: ${msg.price} x ${msg.size}`);
  }

  if (msg.event_type === "auction.settled") {
    console.log(`Auction ${msg.auction_id} settled at ${msg.clearing_price}`);
  }

  if (msg.event_type === "auction.cancelled") {
    console.log(`Auction ${msg.auction_id} was cancelled`);
  }
});
```

**Event types summary:**

| Event type | Who receives it | Description |
| - | - | - |
| `auction.invited` | Maker | You have been invited to submit a quote |
| `auction.quote_received` | Originator | A maker submitted or revised a quote |
| `auction.quote_withdrawn` | Originator | A maker withdrew their active quote |
| `auction.settled` | All participants | Auction executed at clearing price |
| `auction.cancelled` | All participants | Originator cancelled the auction |

<CardGroup cols={2}>
  <Card title="WebSocket Streams" icon="bolt" href="/websocket/market-data-websocket">
    Full WebSocket connection guide and reconnection best practices.
  </Card>

  <Card title="Trading" icon="arrow-right-arrow-left" href="/guides/overview">
    Standard order entry via the Execution API.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.