{
  "openapi": "3.1.0",
  "info": {
    "title": "Star Quest internal Arena trade admission",
    "version": "2026-10-07.1",
    "description": "Implemented for coordinated rollout; dormant until STARQUEST_ARENA_TRADING_DIR is configured. Not evidence of SFO deployment, order activation or delegated partner access. Funding and real-value execution remain paused."
  },
  "servers": [
    {
      "url": "https://starquest.live",
      "description": "Intended game origin. Check deployment/configuration before calling."
    }
  ],
  "paths": {
    "/api/arena/connect/trading/journal": {
      "post": {
        "operationId": "arena_trade_journal",
        "summary": "Journal",
        "description": "Private ordered journal. Bootstrap with null stream_id and after=0, then persist and supply stream_id. At most 100 events per page. No pruning. A different stream or ahead cursor returns 409. Poll snapshots are not admission.",
        "security": [
          {
            "ArenaTime": [],
            "ArenaNonce": [],
            "ArenaSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JournalInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Committed source response. Not a claim of engine execution.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Journal"
                }
              }
            }
          },
          "400": {
            "description": "Malformed input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid service signature or consumed nonce.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflicting retry or journal identity/cursor.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Disabled or unconfirmed operation. Recover with the original request and terms.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/arena/connect/trading/admit": {
      "post": {
        "operationId": "arena_trade_admit",
        "summary": "Admit",
        "description": "Durable exact intent admission or rejection, with a 5-second new-execution deadline. Never changes balances. Preserve original business ID and all terms on retry. A destroyed station may still win on points; join_closed is not outcome elimination.",
        "security": [
          {
            "ArenaTime": [],
            "ArenaNonce": [],
            "ArenaSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AdmissionInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Committed source response. Not a claim of engine execution.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdmissionReceipt"
                }
              }
            }
          },
          "400": {
            "description": "Malformed input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid service signature or consumed nonce.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflicting retry or journal identity/cursor.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Disabled or unconfirmed operation. Recover with the original request and terms.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/arena/connect/trading/acknowledge": {
      "post": {
        "operationId": "arena_trade_acknowledge",
        "summary": "Acknowledge",
        "description": "Acknowledge an accepted journal event only after its executed or rejected engine outcome is durably recoverable. Exact retry succeeds, conflicting reuse returns409. Timeout is not a permanent rejection.",
        "security": [
          {
            "ArenaTime": [],
            "ArenaNonce": [],
            "ArenaSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AcknowledgmentInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Committed source response. Not a claim of engine execution.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgment"
                }
              }
            }
          },
          "400": {
            "description": "Malformed input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid service signature or consumed nonce.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflicting retry or journal identity/cursor.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Disabled or unconfirmed operation. Recover with the original request and terms.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/arena/connect/trading/barrier": {
      "post": {
        "operationId": "arena_trade_barrier",
        "summary": "Barrier",
        "description": "Settlement readiness requires a terminal source record, healthy journal and zero unacknowledged admissions. Ticket expiration alone never drains pending admissions. Check stream, match and terminal hash before settlement.",
        "security": [
          {
            "ArenaTime": [],
            "ArenaNonce": [],
            "ArenaSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BarrierInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Committed source response. Not a claim of engine execution.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Barrier"
                }
              }
            }
          },
          "400": {
            "description": "Malformed input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid service signature or consumed nonce.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflicting retry or journal identity/cursor.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Disabled or unconfirmed operation. Recover with the original request and terms.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ArenaTime": {
        "type": "apiKey",
        "in": "header",
        "name": "x-arena-time",
        "description": "13 decimal Unix UTC milliseconds within 30 seconds."
      },
      "ArenaNonce": {
        "type": "apiKey",
        "in": "header",
        "name": "x-arena-nonce",
        "description": "Fresh43-character base64url nonce; durable one-use PostgreSQL claim."
      },
      "ArenaSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "x-arena-signature",
        "description": "HMAC-SHA256 using existing first-party connector protocol. Not a browser API key."
      }
    },
    "schemas": {
      "Snapshot": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "match_id",
          "room",
          "mode",
          "ruleset",
          "tick",
          "observed_at",
          "eliminated",
          "join_closed",
          "ended",
          "winner",
          "reason"
        ],
        "properties": {
          "match_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "room": {
            "type": "string"
          },
          "mode": {
            "type": "string"
          },
          "ruleset": {
            "type": "string"
          },
          "tick": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "observed_at": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "eliminated": {
            "type": "array",
            "items": {
              "type": "boolean"
            },
            "minItems": 4,
            "maxItems": 4
          },
          "join_closed": {
            "type": "array",
            "items": {
              "type": "boolean"
            },
            "minItems": 4,
            "maxItems": 4
          },
          "ended": {
            "type": "boolean"
          },
          "winner": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 3
              },
              {
                "type": "null"
              }
            ]
          },
          "reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "AdmissionInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "stream_id",
          "match_id",
          "owner",
          "request_id",
          "order_digest",
          "outcome"
        ],
        "properties": {
          "stream_id": {
            "type": "string",
            "format": "uuid"
          },
          "match_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "owner": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "request_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
          },
          "order_digest": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "outcome": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3
          }
        }
      },
      "AdmissionEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "stream_id",
          "match_id",
          "owner",
          "request_id",
          "order_digest",
          "outcome",
          "accepted",
          "reason",
          "accepted_tick",
          "accepted_at",
          "execute_before",
          "snapshot"
        ],
        "properties": {
          "schema": {
            "const": "starquest.trade-admission.v1"
          },
          "stream_id": {
            "type": "string",
            "format": "uuid"
          },
          "match_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "owner": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "request_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
          },
          "order_digest": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "outcome": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3
          },
          "accepted": {
            "type": "boolean"
          },
          "reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "accepted_tick": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "accepted_at": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "execute_before": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "snapshot": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Snapshot"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "AdmissionReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "stream_id",
          "match_id",
          "owner",
          "request_id",
          "order_digest",
          "outcome",
          "accepted",
          "reason",
          "accepted_tick",
          "accepted_at",
          "execute_before",
          "snapshot",
          "event_sequence",
          "event_hash"
        ],
        "properties": {
          "schema": {
            "const": "starquest.trade-admission.v1"
          },
          "stream_id": {
            "type": "string",
            "format": "uuid"
          },
          "match_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "owner": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "request_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
          },
          "order_digest": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "outcome": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3
          },
          "accepted": {
            "type": "boolean"
          },
          "reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "accepted_tick": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "accepted_at": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "execute_before": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "snapshot": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Snapshot"
              },
              {
                "type": "null"
              }
            ]
          },
          "event_sequence": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "event_hash": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "JournalInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "stream_id",
          "after"
        ],
        "properties": {
          "stream_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "after": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        }
      },
      "Event": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "stream_id",
          "sequence",
          "kind",
          "match_id",
          "observed_at",
          "previous_hash",
          "payload",
          "hash"
        ],
        "properties": {
          "schema": {
            "const": "starquest.trade-event.v1"
          },
          "stream_id": {
            "type": "string",
            "format": "uuid"
          },
          "sequence": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "kind": {
            "enum": [
              "state",
              "admission",
              "terminal"
            ]
          },
          "match_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "observed_at": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "previous_hash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "payload": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Snapshot"
              },
              {
                "$ref": "#/components/schemas/AdmissionEvent"
              }
            ]
          },
          "hash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        }
      },
      "Journal": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "stream_id",
          "healthy",
          "events",
          "cursor",
          "more",
          "observed_at"
        ],
        "properties": {
          "schema": {
            "const": "starquest.trade-feed.v1"
          },
          "stream_id": {
            "type": "string",
            "format": "uuid"
          },
          "healthy": {
            "type": "boolean"
          },
          "events": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          },
          "cursor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "more": {
            "type": "boolean"
          },
          "observed_at": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        }
      },
      "AcknowledgmentInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "sequence",
          "event_hash",
          "decision",
          "receipt_hash"
        ],
        "properties": {
          "sequence": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "event_hash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "decision": {
            "enum": [
              "executed",
              "rejected"
            ]
          },
          "receipt_hash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        }
      },
      "Acknowledgment": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "sequence",
          "event_hash",
          "decision",
          "receipt_hash",
          "acknowledged"
        ],
        "properties": {
          "sequence": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "event_hash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "decision": {
            "enum": [
              "executed",
              "rejected"
            ]
          },
          "receipt_hash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "acknowledged": {
            "const": true
          }
        }
      },
      "BarrierInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "match_id"
        ],
        "properties": {
          "match_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          }
        }
      },
      "Barrier": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "stream_id",
          "match_id",
          "terminal",
          "terminal_sequence",
          "terminal_hash",
          "pending_admissions",
          "settlement_ready",
          "snapshot"
        ],
        "properties": {
          "schema": {
            "const": "starquest.trade-barrier.v1"
          },
          "stream_id": {
            "type": "string",
            "format": "uuid"
          },
          "match_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "terminal": {
            "type": "boolean"
          },
          "terminal_sequence": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "terminal_hash": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "pending_admissions": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "settlement_ready": {
            "type": "boolean"
          },
          "snapshot": {
            "$ref": "#/components/schemas/Snapshot"
          }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  },
  "externalDocs": {
    "url": "https://github.com/seanprescott/starquest/blob/main/docs/arena-trading-protocol.md",
    "description": "Exact signing, ordering, recovery and rollout contract"
  },
  "x-activation": "disabled-by-default",
  "x-partner-write-auth": false,
  "x-value-movement": false
}
