> ## 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. # Verify originator capacity without reserving it > Returns a point-in-time, read-only capacity verdict for the authenticated originator across every requested route. The response exposes bounded executable quantity, never raw collateral, position, venue-account, credential, or control-group data. No auction, journal event, or risk reservation is created. POST /v1/auctions always repeats the same capacity calculation and reserves atomically, so a successful preflight is evidence rather than a guarantee against concurrent use. This call is not rate-limited and ignores the idempotency key. ## OpenAPI ````yaml /openapi/agora.yaml post /v1/auctions/preflight openapi: 3.1.0 info: title: Agora Auction House API version: 1.0.0-pilot description: | Private first-price sealed auctions for venue-backed prediction contracts. Active auctions are never published through an unauthenticated or global feed. All price and quantity values are integer atoms. ## Authentication Every `/v1` operation requires a first-party Kairos session JWT (`Authorization: Bearer `, RS256, `iss: kairos.trade`, `aud: kairos-api`, `ver: 1`, an expiry claim, and a subject enrolled in the Auction House). Any other credential shape — missing header, wrong audience, revoked session, unenrolled subject — is rejected with `401` before the handler runs. There is no API-key or anonymous tier. Browser WebSocket clients pass the same JWT as the `Sec-WebSocket-Protocol` subprotocol pair `authorization, Bearer.`. Every session is granted the `auction:create` and `auction:quote` capabilities; they only allow the request to reach the fail-closed Go-owned economic policy store, which remains the real authorization boundary. ## Errors Every error body is a flat JSON object: `{"error": ""}`, plus a `"message"` field on rejections raised by the auction engine. Codes are stable; `message` is descriptive and must not be parsed. `422` rejections carry the durable auction reason code (for example `INVALID_PRICE_TICK`, `UNAUTHORIZED_SIZE`, `SERVICE_CAPACITY_EXCEEDED`) as the `error` value. ## Request limits Request bodies are capped at 1 MiB (`413 payload_too_large`). JSON is parsed strictly: no `null` values, no duplicate object keys, no unknown fields, no trailing data, and at most 64 levels of nesting. Owner-routing headers (`X-Service-Token`, `X-Agora-Peer`, `X-Agora-Active-Only`, `X-Agora-Owner-Read-Fallback`) are internal capabilities and are rejected with `403` on the public listener. ## Rate limiting Only state-changing operations are metered, by a per-account and per-auction token bucket owned by the authoritative shard, evaluated before any risk reservation or journal write. Exceeding a bucket returns `429 auction_mutation_rate_limited`. No `Retry-After` or `X-RateLimit-*` headers are emitted; back off and retry with the same idempotency key. Reads, both preflight calls, and the stream are not metered. servers: - url: https://agora.kairos.trade description: >- Production. Agora is allow-listed RFQ and the production host is not currently enabled, so this base URL does not answer public requests yet. - url: https://staging-agora.kairos.trade description: Staging. security: - bearerAuth: [] paths: /v1/auctions/preflight: post: summary: Verify originator capacity without reserving it description: | Returns a point-in-time, read-only capacity verdict for the authenticated originator across every requested route. The response exposes bounded executable quantity, never raw collateral, position, venue-account, credential, or control-group data. No auction, journal event, or risk reservation is created. POST /v1/auctions always repeats the same capacity calculation and reserves atomically, so a successful preflight is evidence rather than a guarantee against concurrent use. This call is not rate-limited and ignores the idempotency key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAuction' responses: '200': description: Current originator route-capacity evidence content: application/json: schema: $ref: '#/components/schemas/OriginatorPreflight' '400': $ref: '#/components/responses/InvalidJSON' '401': $ref: '#/components/responses/Unauthorized' '403': description: | `forbidden` when the session lacks the `auction:create` capability, or `internal_routing_headers_forbidden` when the request carries an owner-routing header. content: application/json: schema: $ref: '#/components/schemas/Error' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/Rejected' '500': description: | `internal_error` — this owner cannot verify authority safely (draining, unhealthy clock or journal capacity, saturated active auction cache), or the admission authority returned evidence that failed its own invariants. No 503 is emitted on this path. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: internal_error message: auction request could not be completed components: schemas: CreateAuction: type: object required: - market_id - outcome_id - side - fill_instruction - hard_reserve_price_atoms - slippage_reference_policy - max_cumulative_slippage_bps - venue_scope - audience_mode - identity_disclosure_mode - allocation_priority_policy - max_total_execution_time_ms properties: idempotency_key: type: string description: May be supplied instead of the header market_id: type: string maxLength: 128 outcome_id: type: string maxLength: 128 side: enum: - BUY - SELL fill_instruction: enum: - FOK - FLEXIBLE fixed_quantity_atoms: type: integer format: int64 minimum: 1 flexible_fill: $ref: '#/components/schemas/FlexibleFill' hard_reserve_price_atoms: $ref: '#/components/schemas/PriceAtoms' slippage_reference_price_atoms: allOf: - $ref: '#/components/schemas/PriceAtoms' description: Required only when slippage_reference_policy is APPROVED_EXPLICIT. slippage_reference_policy: enum: - PUBLIC_EXECUTABLE_VWAP - APPROVED_EXPLICIT max_cumulative_slippage_bps: type: integer format: int64 minimum: 0 maximum: 10000 minimum_private_improvement_bps: type: integer format: int64 minimum: 0 maximum: 10000 maximum_mm_concentration_bps: type: integer format: int64 minimum: 1 maximum: 10000 default: 10000 minimum_mm_reliability_tier: enum: - UNRATED - C - B - A default: UNRATED allocation_priority_policy: enum: - PRICE_FIRST - COMPLETION_FIRST description: >- Frozen before invitations; price-first minimizes marginal economics while completion-first may prefer one firm able to complete the target. auction_ttl_ms: type: integer format: int64 minimum: 2000 maximum: 2592000000 default: 5000 description: >- Custom sealed bidding window from 2 seconds through 30 days. Omit or send 0 to accept the 5-second default. venue_scope: type: array minItems: 1 maxItems: 8 items: type: string maxLength: 64 audience_mode: enum: - MANUAL - SAVED_GROUP - RECOMMENDED allowed_participants: type: array maxItems: 16 items: type: string maxLength: 128 saved_group_id: type: string maxLength: 128 excluded_participants: type: array maxItems: 16 items: type: string maxLength: 128 max_recipients: type: integer minimum: 1 maximum: 16 default: 16 identity_disclosure_mode: enum: - CLASS_ONLY - REVEAL_TO_INVITEES - REVEAL_ON_AWARD fallback_ladder: type: array maxItems: 4 items: $ref: '#/components/schemas/FallbackRung' max_total_execution_time_ms: type: integer format: int64 minimum: 1 maximum: 120000 client_metadata: type: object additionalProperties: type: string description: >- Bounded non-authoritative display metadata, at most 32 entries and 4 KiB total. market_title and market_provider provide the catalog label. Optional client_order_id is a 1–64 character desk reconciliation reference using letters, numbers, or . _ : / -; it is originator-only and should also derive the create idempotency key. OriginatorPreflight: type: object required: - status - requested_quantity_atoms - maximum_executable_quantity_atoms - checked_at - valid_until - routes properties: status: enum: - EXECUTABLE - INSUFFICIENT_CAPACITY requested_quantity_atoms: type: string pattern: ^[1-9]\d*$ description: Requested maximum quantity encoded exactly. maximum_executable_quantity_atoms: type: string pattern: ^(0|[1-9]\d*)$ description: Minimum currently executable quantity across all requested routes. checked_at: type: string format: date-time valid_until: type: string format: date-time description: Earliest risk mapping: null rule: null or fee authority expiry across the route set.: null routes: type: array minItems: 1 maxItems: 5 items: $ref: '#/components/schemas/OriginatorRouteCapacity' Error: type: object required: - error description: | Flat error envelope used by every JSON error response. `message` is present on rejections raised by the auction engine and absent on transport-level rejections such as `invalid_list_page` or `payload_too_large`. Match on `error`; never parse `message`. properties: error: type: string description: Stable machine-readable code or the durable auction reason code on a 422/409 rejection.: null message: type: string description: Human-readable detail; not a stable contract. FlexibleFill: type: object required: - min_fill_quantity_atoms - target_fill_quantity_atoms - max_fill_quantity_atoms - objective_mode properties: min_fill_quantity_atoms: type: integer format: int64 minimum: 1 target_fill_quantity_atoms: type: integer format: int64 minimum: 1 max_fill_quantity_atoms: type: integer format: int64 minimum: 1 objective_mode: enum: - STOP_AT_TARGET - SEEK_MAXIMUM description: >- Minimum, target, and maximum are always explicit; SEEK_MAXIMUM may continue beyond the target but never beyond maximum. PriceAtoms: type: integer format: int64 minimum: 0 maximum: 10000 description: One atom is 0.01 cent of probability-dollar price. FallbackRung: type: object required: - action properties: action: enum: - EXECUTE - CANCEL_REMAINDER default: EXECUTE rail: enum: - VENUE_NATIVE_RFQ - CLOB venue: type: string limit_price_atoms: $ref: '#/components/schemas/PriceAtoms' minimum_quantity_atoms: type: integer format: int64 minimum: 1 maximum_quantity_atoms: type: integer format: int64 minimum: 1 maximum_fraction_bps: type: integer format: int64 minimum: 1 maximum: 10000 default: 10000 timeout_ms: type: integer format: int64 minimum: 1 default: 2000 maximum_quote_age_ms: type: integer format: int64 minimum: 1 maximum: 5000 default: 500 allow_partial: type: boolean on_unavailable: enum: - CONTINUE - STOP default: CONTINUE on_reject: enum: - CONTINUE - STOP default: CONTINUE fee_profile: $ref: '#/components/schemas/FeeProfile' description: Server-pinned; caller values are not authoritative. route_rule_profile: $ref: '#/components/schemas/RouteRuleProfile' description: >- Server-pinned executable venue and mapping contract; caller values are not authoritative. OriginatorRouteCapacity: type: object required: - venue - rails - resource_type - maximum_executable_quantity_atoms - risk_source_sequence - risk_valid_until - authority_valid_until properties: venue: type: string maxLength: 64 rails: type: array minItems: 1 maxItems: 3 uniqueItems: true items: enum: - PRIVATE_BLOCK - VENUE_NATIVE_RFQ - CLOB resource_type: enum: - COLLATERAL - POSITION maximum_executable_quantity_atoms: type: string pattern: ^(0|[1-9]\d*)$ risk_source_sequence: type: string pattern: ^[1-9]\d*$ description: Opaque venue-account authority sequence. risk_valid_until: type: string format: date-time authority_valid_until: type: string format: date-time description: Earliest mapping route-rule: null fee: null or execution-deadline expiry for this route.: null FeeProfile: type: object required: - fee_profile_id - fee_profile_version - model - rate_ppm - fixed_fee_atoms - minimum_fee_atoms - prediction_fee_scale_ppm - rounding_mode - valid_until properties: fee_profile_id: type: string fee_profile_version: type: string model: enum: - NONE - NOTIONAL_PPM - PREDICTION_MARKET default: NONE rate_ppm: type: integer format: int64 minimum: -1000000 maximum: 1000000 fixed_fee_atoms: type: integer format: int64 minimum_fee_atoms: type: integer format: int64 minimum: 0 prediction_fee_scale_ppm: type: integer format: int64 minimum: -1000000 maximum: 1000000 rounding_mode: enum: - AGAINST_ORIGINATOR - NEAREST default: AGAINST_ORIGINATOR valid_until: type: string format: date-time RouteRuleProfile: type: object required: - version - venue - rail - mapping_version - venue_market_id - venue_outcome_id - route_id - price_tick_atoms - quantity_tick_atoms - minimum_order_atoms - maximum_order_atoms - atomic - self_trade_prevention_mode - control_group_version - valid_from - valid_until - mapping_valid_from - mapping_valid_until properties: version: type: string venue: type: string rail: enum: - VENUE_NATIVE_RFQ - CLOB mapping_version: type: string venue_market_id: type: string venue_outcome_id: type: string route_id: type: string price_tick_atoms: type: integer format: int64 minimum: 1 quantity_tick_atoms: type: integer format: int64 minimum: 1 minimum_order_atoms: type: integer format: int64 minimum: 1 maximum_order_atoms: type: integer format: int64 minimum: 1 atomic: type: boolean self_trade_prevention_mode: enum: - CONTROL_GROUP_REJECT control_group_version: type: string valid_from: type: string format: date-time valid_until: type: string format: date-time mapping_valid_from: type: string format: date-time mapping_valid_until: type: string format: date-time responses: InvalidJSON: description: | `invalid_json` (unparseable, `null`, duplicate key, unknown field, or over 64 levels deep) or `multiple_json_values` (trailing data after the request object). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_json message: request body is not valid JSON Unauthorized: description: | The bearer session is absent, malformed, expired, revoked, signed by an unrecognized key, carries the wrong issuer, audience, or schema version, or its subject is not enrolled in the Auction House. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: authentication required PayloadTooLarge: description: '`payload_too_large` — the request body exceeded 1 MiB.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: payload_too_large Rejected: description: | Admission, tick, reserve, audience, or state rejection. `error` is the durable auction reason code — for example `INVALID_REQUEST`, `TTL_OUT_OF_RANGE`, `BELOW_MIN_BLOCK_SIZE`, `NO_ELIGIBLE_MMS`, `PARTICIPANT_INELIGIBLE`, `SERVICE_CAPACITY_EXCEEDED`, `ATOMICITY_UNAVAILABLE` — or `auction_rejected` for an untyped request-shape failure. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: TTL_OUT_OF_RANGE message: TTL_OUT_OF_RANGE securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.