> ## 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. # Submit or revise one firm executable price and quantity > Invited makers only. Supply the idempotency key in the header or request body. If both are present, they must match exactly. Revisions are strictly sequential: the first quote must be revision 1 and each later quote exactly one higher than the caller's current revision. ## OpenAPI ````yaml /openapi/agora.yaml post /v1/auctions/{auctionID}/quotes 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/{auctionID}/quotes: parameters: - $ref: '#/components/parameters/AuctionID' post: summary: Submit or revise one firm executable price and quantity description: | Invited makers only. Supply the idempotency key in the header or request body. If both are present, they must match exactly. Revisions are strictly sequential: the first quote must be revision 1 and each later quote exactly one higher than the caller's current revision. parameters: - $ref: '#/components/parameters/OptionalIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitQuote' responses: '200': description: Identical idempotent replay content: application/json: schema: $ref: '#/components/schemas/Quote' '201': description: Quote journaled and accepted content: application/json: schema: $ref: '#/components/schemas/Quote' '400': description: >- `invalid_json`, `multiple_json_values`, `idempotency_key_mismatch`, or `invalid_auction_id`. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': description: | `forbidden` when the session lacks the `auction:quote` capability, or `internal_routing_headers_forbidden` when the request carries an owner-routing header. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Auction absent or not visible to the caller '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '422': description: | Durably journaled bid rejection. `error` is the reason code: `INVALID_PRICE_RANGE`, `INVALID_PRICE_TICK`, `INVALID_QUANTITY_TICK`, `BID_INVALID`, `UNAUTHORIZED_SIZE` (over the frozen approved size), `LATE_BID` (the auction closed), or a reason returned by the reservation authority. A missing or oversized idempotency key is also rejected here as `auction_rejected`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: INVALID_PRICE_TICK message: INVALID_PRICE_TICK '429': $ref: '#/components/responses/MutationRateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/OwnerUnavailable' components: parameters: AuctionID: name: auctionID in: path required: true description: Canonical UUID whose first character is the owner shard (0, 1, or 2). schema: type: string format: uuid OptionalIdempotencyKey: name: Idempotency-Key in: header required: false description: >- Required here or in the JSON body; both values must match when supplied together. schema: type: string minLength: 1 maxLength: 200 schemas: SubmitQuote: type: object required: - revision - price_atoms - max_executable_quantity_atoms additionalProperties: false properties: idempotency_key: type: string description: May be supplied instead of the header revision: type: integer format: int64 minimum: 1 price_atoms: $ref: '#/components/schemas/PriceAtoms' max_executable_quantity_atoms: type: integer format: int64 minimum: 1 Quote: type: object required: - quote_id - auction_id - revision - price_atoms - max_executable_quantity_atoms - receive_sequence - received_at - status properties: quote_id: type: string format: uuid auction_id: type: string format: uuid revision: type: string pattern: ^(0|[1-9]\d*)$ description: Opaque unsigned quote revision; compare as a decimal string. price_atoms: $ref: '#/components/schemas/PriceAtoms' max_executable_quantity_atoms: type: integer format: int64 receive_sequence: type: string pattern: ^(0|[1-9]\d*)$ description: >- Participant-scoped durable acknowledgement sequence encoded as an opaque decimal string; private FIFO coordinates are never exposed. received_at: type: string format: date-time status: enum: - ACTIVE - WITHDRAWN - SUPERSEDED - FROZEN - SELECTED - INELIGIBLE 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. PriceAtoms: type: integer format: int64 minimum: 0 maximum: 10000 description: One atom is 0.01 cent of probability-dollar price. responses: 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 Conflict: description: | `IDEMPOTENCY_CONFLICT` when the idempotency key was already used with a different request, or `REVISION_CONFLICT` when a quote revision is not exactly one higher than the caller's current revision. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: IDEMPOTENCY_CONFLICT message: IDEMPOTENCY_CONFLICT PayloadTooLarge: description: '`payload_too_large` — the request body exceeded 1 MiB.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: payload_too_large MutationRateLimited: description: | `auction_mutation_rate_limited` — the per-account or per-auction mutation bucket is exhausted, or the durable event budget reserved for auction lifecycle work has been reached. No `Retry-After` or `X-RateLimit-*` header is emitted. Retrying with the same idempotency key is safe. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: auction_mutation_rate_limited message: auction mutation rate limit exceeded InternalError: description: | `internal_error` — the owner is draining, its journal is unavailable, invitation publication for an idempotent replay is still pending, or an untyped dependency failure occurred. `encode_create`, `encode_quote`, and `encode_quote_preflight` indicate the request could not be re-encoded for owner routing. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: internal_error message: auction request could not be completed OwnerUnavailable: description: | The owning shard for this auction could not be reached or answered unusably: `auction_owner_unavailable`, `owner_routing_unavailable`, or `owner_response_invalid`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: auction_owner_unavailable securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.