Run Private Block Trade Auctions on the Kairos Agora API

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.

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.

How an auction works

A typical Agora auction runs through four phases:

Originator creates the auction

The buy-side principal (originator) opens an auction, specifying the market, side, size, and how long makers have to quote.

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.

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.

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

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
  }'

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:

{
  "eligible": true,
  "available_capacity": 50000,
  "required_collateral": 6200,
  "warnings": []
}

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.

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.

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"
  }'

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:

{
  "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.

curl "https://agora.kairos.trade/v1/auctions/auc_7gXp2mNkQwY3" \
  -H "Authorization: Bearer $KAIROS_JWT"

Example response (originator view):

{
  "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

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.

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
  }'

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:

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

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.

Check maker capacity before quoting

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

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:

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:

curl -X POST "https://agora.kairos.trade/v1/auctions/auc_7gXp2mNkQwY3/cancel" \
  -H "Authorization: Bearer $KAIROS_JWT"

Example response:

{
  "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:

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.

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

WebSocket Streams

Full WebSocket connection guide and reconnection best practices.

Trading

Standard order entry via the Execution API.

Get Started

Core Concepts

Learn Trading

Guides

Perpetual Futures

External Execution

Trading

Compliance

Updates

Run Private Block Trade Auctions on the Kairos Agora API

How an auction works

Step 1 — Run a preflight check

Step 2 — Create an auction

Step 3 — Monitor the auction (originator)

List all your auctions

Step 4 — Submit a quote (market maker)

Check maker capacity before quoting

Withdraw a quote

Cancel an auction

Check your invitation inbox

Real-time auction events via WebSocket

WebSocket Streams

Trading

​How an auction works

​Step 1 — Run a preflight check

​Step 2 — Create an auction

​Step 3 — Monitor the auction (originator)

​List all your auctions

​Step 4 — Submit a quote (market maker)

​Check maker capacity before quoting

​Withdraw a quote

​Cancel an auction

​Check your invitation inbox

​Real-time auction events via WebSocket

WebSocket Streams

Trading

How an auction works

Step 1 — Run a preflight check

Step 2 — Create an auction

Step 3 — Monitor the auction (originator)

List all your auctions

Step 4 — Submit a quote (market maker)

Check maker capacity before quoting

Withdraw a quote

Cancel an auction

Check your invitation inbox

Real-time auction events via WebSocket