{ "paths": { "/wallet/v1/callbacks/{operatorCode}": { "post": { "operationId": "wallet_acceptCallback", "summary": "Accept a signed operator wallet callback", "security": [ { "W_WalletKeyId": [], "W_WalletTimestamp": [], "W_WalletMessageId": [], "W_WalletSignature": [] } ], "parameters": [ { "name": "operatorCode", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } }, { "name": "X-Wallet-Key-Id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/W_KeyId" } }, { "name": "X-Wallet-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\d{10}$" } }, { "name": "X-Wallet-Message-Id", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/W_Uuid" } }, { "name": "X-Wallet-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{86}$" } } ], "requestBody": { "required": true, "content": { "application/vnd.23rgs.wallet-callback+json": { "schema": { "$ref": "#/components/schemas/W_CallbackPayload" } } } }, "responses": { "202": { "description": "New callback accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_CallbackAcceptance" } } } }, "200": { "description": "Exact duplicate callback replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_CallbackAcceptance" } } } }, "400": { "description": "Invalid headers, JSON, media type, or payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "401": { "description": "Inactive/unknown key or operator, stale timestamp, or invalid signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "409": { "description": "Message, operation, terminal tuple, statement, or remote transaction identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } } } } }, "/operator/v1/wallet/signing-keys": { "post": { "operationId": "wallet_createSigningKey", "summary": "Register an operator Ed25519 callback/response key", "security": [ { "OperatorBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_SigningKeyCreate" } } } }, "responses": { "201": { "description": "Key created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_SigningKeyResult" } } } }, "200": { "description": "Idempotent active-key registration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_SigningKeyResult" } } } }, "400": { "description": "Invalid request, PEM, algorithm, or validity interval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "401": { "description": "Operator bearer authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "409": { "description": "Key ID conflicts with an existing key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } } }, "x-operator-scope": "wallet-admin" } }, "/operator/v1/wallet/signing-keys/{keyId}": { "delete": { "operationId": "wallet_revokeSigningKey", "summary": "Revoke an unbound active signing key", "security": [ { "OperatorBearer": [] } ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/W_KeyId" } } ], "responses": { "204": { "description": "Key revoked" }, "401": { "description": "Operator bearer authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "404": { "description": "No active key with this key ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "409": { "description": "Active connector still binds this response signing key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } } }, "x-operator-scope": "wallet-admin" } }, "/operator/v1/external-wallet/reconciliation/runs/{runId}": { "get": { "operationId": "wallet_getExternalReconciliationRun", "summary": "Get a reconciliation run created from a signed balance statement", "security": [ { "OperatorBearer": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/W_Uuid" } } ], "responses": { "200": { "description": "Reconciliation run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_ReconciliationRun" } } } }, "401": { "description": "Operator bearer authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "404": { "description": "Run does not belong to this operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } } }, "x-operator-scope": "wallet-admin" } }, "/operator/v1/external-wallet/mode": { "put": { "operationId": "wallet_setExternalWalletMode", "summary": "Set custodial or signed external settlement mode", "security": [ { "OperatorBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_WalletModeRequest" } } } }, "responses": { "200": { "description": "Mode stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_WalletModeResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "401": { "description": "Operator bearer authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "503": { "description": "External wallet runtime or active connector/key unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } } }, "x-operator-scope": "wallet-admin", "description": "Requires wallet-admin and echo.target matching mode." } }, "/operator/v1/external-wallet/connector": { "put": { "operationId": "wallet_setExternalWalletConnector", "summary": "Configure the operator-hosted signed-wallet endpoint", "security": [ { "OperatorBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_ConnectorRequest" } } } }, "responses": { "200": { "description": "Active connector stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_ConnectorResult" } } } }, "400": { "description": "Invalid URL, credentials in URL, insecure non-loopback endpoint, or invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "401": { "description": "Operator bearer authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "404": { "description": "Active response signing key is absent or outside validity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } } }, "x-operator-scope": "wallet-admin", "description": "Requires wallet-admin and echo.target matching endpoint exactly, including URL case." } }, "/operator/v1/external-wallet/operations": { "post": { "operationId": "wallet_executeExternalOperation", "summary": "Durably submit an external-wallet operation", "security": [ { "OperatorBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_ExternalOperationCommand" } } } }, "responses": { "201": { "description": "New operation; status may be approved, declined, or unknown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_ExternalOperationResult" } } } }, "200": { "description": "Idempotent duplicate operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_ExternalOperationResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "401": { "description": "Operator bearer authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "409": { "description": "Operation request, cancellation, remote identity, or terminal evidence conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "503": { "description": "Active connector/key unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } } }, "x-operator-scope": "wallet-admin" } }, "/operator/v1/external-wallet/operations/{operationId}": { "get": { "operationId": "wallet_getExternalOperation", "summary": "Get a durable external-wallet operation result", "security": [ { "OperatorBearer": [] } ], "parameters": [ { "name": "operationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/W_Uuid" } } ], "responses": { "200": { "description": "Stored operation result; duplicate is always true for lookup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_ExternalOperationResult" } } } }, "401": { "description": "Operator bearer authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } }, "404": { "description": "Operation does not exist for this operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/W_Error" } } } } }, "x-operator-scope": "wallet-admin" } } }, "components": { "schemas": { "W_Uuid": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "W_MoneyPositive": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "W_MoneyNonnegative": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "W_Currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "W_KeyId": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "W_Error": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "INVALID_REQUEST", "WALLET_CALLBACK_AUTHENTICATION_FAILED", "WALLET_CALLBACK_CONFLICT", "OPERATOR_AUTHENTICATION_FAILED", "WALLET_SIGNING_KEY_NOT_FOUND", "WALLET_SIGNING_KEY_IN_USE", "WALLET_CALLBACK_RESOURCE_NOT_FOUND", "EXTERNAL_WALLET_CONFLICT", "EXTERNAL_WALLET_UNAVAILABLE", "EXTERNAL_WALLET_OPERATION_NOT_FOUND", "WALLET_RESPONSE_SIGNING_KEY_NOT_FOUND", "INTERNAL_ERROR", "WALLET_TRANSACTION_CONFLICT" ] }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "code", "path", "message" ], "properties": { "code": { "type": "string" }, "path": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] } }, "message": { "type": "string" } } } } } }, "W_FinalizedCallback": { "type": "object", "additionalProperties": false, "required": [ "type", "operationId", "externalTransactionId", "status", "amount", "currency", "balance" ], "properties": { "type": { "const": "transaction.finalized" }, "operationId": { "$ref": "#/components/schemas/W_Uuid" }, "externalTransactionId": { "type": "string", "minLength": 1, "maxLength": 256 }, "status": { "type": "string", "enum": [ "approved", "declined", "reversed", "manual_review" ] }, "amount": { "$ref": "#/components/schemas/W_MoneyPositive" }, "currency": { "$ref": "#/components/schemas/W_Currency" }, "balance": { "$ref": "#/components/schemas/W_MoneyNonnegative" } } }, "W_StatementBalance": { "type": "object", "additionalProperties": false, "required": [ "playerId", "currency", "balance" ], "properties": { "playerId": { "type": "string", "minLength": 1, "maxLength": 256 }, "currency": { "$ref": "#/components/schemas/W_Currency" }, "balance": { "$ref": "#/components/schemas/W_MoneyNonnegative" } } }, "W_BalanceStatementCallback": { "type": "object", "additionalProperties": false, "required": [ "type", "statementId", "asOf", "balances" ], "properties": { "type": { "const": "balance.statement" }, "statementId": { "type": "string", "minLength": 1, "maxLength": 256 }, "asOf": { "type": "string", "format": "date-time" }, "balances": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/W_StatementBalance" } } } }, "W_CallbackPayload": { "oneOf": [ { "$ref": "#/components/schemas/W_FinalizedCallback" }, { "$ref": "#/components/schemas/W_BalanceStatementCallback" } ] }, "W_CallbackAcceptance": { "type": "object", "additionalProperties": false, "required": [ "id", "messageId", "status", "duplicate" ], "properties": { "id": { "$ref": "#/components/schemas/W_Uuid" }, "messageId": { "$ref": "#/components/schemas/W_Uuid" }, "status": { "type": "string", "enum": [ "processed", "manual_review" ] }, "duplicate": { "type": "boolean" }, "reconciliationRunId": { "$ref": "#/components/schemas/W_Uuid" } } }, "W_SigningKeyCreate": { "type": "object", "additionalProperties": false, "required": [ "keyId", "publicKeyPem" ], "properties": { "keyId": { "$ref": "#/components/schemas/W_KeyId" }, "publicKeyPem": { "type": "string", "minLength": 64, "maxLength": 4096 }, "notBefore": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "W_SigningKeyResult": { "type": "object", "additionalProperties": false, "required": [ "keyId", "algorithm", "status" ], "properties": { "keyId": { "$ref": "#/components/schemas/W_KeyId" }, "algorithm": { "const": "Ed25519" }, "status": { "const": "active" }, "notBefore": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "W_WalletModeRequest": { "type": "object", "additionalProperties": false, "required": [ "mode", "echo" ], "properties": { "mode": { "type": "string", "enum": [ "custodial", "external" ] }, "echo": { "type": "object", "required": [ "target" ], "additionalProperties": false, "properties": { "target": { "type": "string", "minLength": 1, "maxLength": 2048 } } } } }, "W_WalletModeResult": { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "custodial", "external" ] } } }, "W_ConnectorRequest": { "type": "object", "additionalProperties": false, "required": [ "endpoint", "responseKeyId", "echo" ], "properties": { "endpoint": { "type": "string", "format": "uri", "maxLength": 2048 }, "responseKeyId": { "$ref": "#/components/schemas/W_KeyId" }, "echo": { "type": "object", "required": [ "target" ], "additionalProperties": false, "properties": { "target": { "type": "string", "minLength": 1, "maxLength": 2048 } } } } }, "W_ConnectorResult": { "type": "object", "additionalProperties": false, "required": [ "endpoint", "responseKeyId", "status" ], "properties": { "endpoint": { "type": "string", "format": "uri" }, "responseKeyId": { "$ref": "#/components/schemas/W_KeyId" }, "status": { "const": "active" } } }, "W_ExternalOperationCommand": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "operationId", "kind", "playerId", "currency", "amount" ], "properties": { "operationId": { "$ref": "#/components/schemas/W_Uuid" }, "playerId": { "type": "string", "minLength": 1, "maxLength": 256 }, "currency": { "$ref": "#/components/schemas/W_Currency" }, "kind": { "const": "debit" }, "amount": { "$ref": "#/components/schemas/W_MoneyPositive" } } }, { "type": "object", "additionalProperties": false, "required": [ "operationId", "kind", "playerId", "currency", "amount" ], "properties": { "operationId": { "$ref": "#/components/schemas/W_Uuid" }, "playerId": { "type": "string", "minLength": 1, "maxLength": 256 }, "currency": { "$ref": "#/components/schemas/W_Currency" }, "kind": { "const": "credit" }, "amount": { "$ref": "#/components/schemas/W_MoneyPositive" } } }, { "type": "object", "additionalProperties": false, "required": [ "operationId", "kind", "playerId", "currency", "originalOperationId" ], "properties": { "operationId": { "$ref": "#/components/schemas/W_Uuid" }, "playerId": { "type": "string", "minLength": 1, "maxLength": 256 }, "currency": { "$ref": "#/components/schemas/W_Currency" }, "kind": { "const": "cancel" }, "originalOperationId": { "$ref": "#/components/schemas/W_Uuid" } } }, { "type": "object", "additionalProperties": false, "required": [ "operationId", "kind", "playerId", "currency" ], "properties": { "operationId": { "$ref": "#/components/schemas/W_Uuid" }, "playerId": { "type": "string", "minLength": 1, "maxLength": 256 }, "currency": { "$ref": "#/components/schemas/W_Currency" }, "kind": { "const": "balance" } } } ] }, "W_ExternalOperationResult": { "type": "object", "additionalProperties": false, "required": [ "id", "operationId", "status", "duplicate", "remoteTransactionId", "balance", "currency" ], "properties": { "id": { "$ref": "#/components/schemas/W_Uuid" }, "operationId": { "$ref": "#/components/schemas/W_Uuid" }, "status": { "type": "string", "enum": [ "pending", "approved", "declined", "unknown", "manual_review", "cancelled" ] }, "duplicate": { "type": "boolean" }, "remoteTransactionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 256 }, "balance": { "oneOf": [ { "$ref": "#/components/schemas/W_MoneyNonnegative" }, { "type": "null" } ] }, "currency": { "$ref": "#/components/schemas/W_Currency" } } }, "W_ReconciliationCase": { "type": "object", "additionalProperties": false, "required": [ "id", "accountId", "playerId", "currency", "externalBalance", "comparisonBalance", "evidenceOperationRecordId", "evidenceOperationId", "delta", "reasonCode", "status", "resolutionNote", "createdAt" ], "properties": { "id": { "$ref": "#/components/schemas/W_Uuid" }, "accountId": { "oneOf": [ { "$ref": "#/components/schemas/W_Uuid" }, { "type": "null" } ] }, "playerId": { "type": "string" }, "currency": { "$ref": "#/components/schemas/W_Currency" }, "externalBalance": { "oneOf": [ { "$ref": "#/components/schemas/W_MoneyNonnegative" }, { "type": "null" } ] }, "comparisonBalance": { "oneOf": [ { "$ref": "#/components/schemas/W_MoneyNonnegative" }, { "type": "null" } ] }, "evidenceOperationRecordId": { "oneOf": [ { "$ref": "#/components/schemas/W_Uuid" }, { "type": "null" } ] }, "evidenceOperationId": { "oneOf": [ { "$ref": "#/components/schemas/W_Uuid" }, { "type": "null" } ] }, "delta": { "oneOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "reasonCode": { "type": "string", "enum": [ "balance_mismatch", "missing_internal_account", "missing_external_balance", "missing_authoritative_evidence" ] }, "status": { "type": "string", "enum": [ "open", "resolved" ] }, "resolutionNote": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "W_ReconciliationRun": { "type": "object", "additionalProperties": false, "required": [ "id", "statementId", "statementAsOf", "evidenceCutoffAt", "status", "balancesChecked", "mismatchCount", "comparisonBasis", "createdAt", "completedAt", "cases" ], "properties": { "id": { "$ref": "#/components/schemas/W_Uuid" }, "statementId": { "type": "string" }, "statementAsOf": { "type": "string", "format": "date-time" }, "evidenceCutoffAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "balancesChecked": { "type": "integer", "minimum": 0 }, "mismatchCount": { "type": "integer", "minimum": 0 }, "comparisonBasis": { "type": "string", "enum": [ "custodial_shadow_legacy", "authoritative_operation_evidence" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cases": { "type": "array", "items": { "$ref": "#/components/schemas/W_ReconciliationCase" } } } } }, "securitySchemes": { "W_WalletKeyId": { "type": "apiKey", "in": "header", "name": "X-Wallet-Key-Id" }, "W_WalletTimestamp": { "type": "apiKey", "in": "header", "name": "X-Wallet-Timestamp" }, "W_WalletMessageId": { "type": "apiKey", "in": "header", "name": "X-Wallet-Message-Id" }, "W_WalletSignature": { "type": "apiKey", "in": "header", "name": "X-Wallet-Signature" } } } }