{ "openapi": "3.1.0", "info": { "title": "ETHGas core API contract (selected operations)", "version": "1.0.0-docs.20261006", "description": "Manually maintained canonical contract subset: login/verify/refresh/logout and whole-block/inclusion order creation/cancellation. NOT the complete API. Source-checked against ethgas-trade-java 10a95ed493b56143390575e5c3131f16a9e684d0 and ethgas-trade-common c46e4f979dd2c67ad94b038aecedf196037738e2. Deployment parity unverified. Schemas describe canonical inputs; v1 may accept additional coercions. No idempotency/replay guarantee is implied. Local backend updates include typed security/admission errors and configurable Retry-After. Deployment has not been verified." }, "servers": [ { "url": "https://hoodi.app.ethgas.com", "description": "Hoodi testing environment" }, { "url": "https://prod-mainnet.ethgas.com", "description": "Mainnet" } ], "externalDocs": { "url": "https://developers.ethgas.com/" }, "paths": { "/api/v1/wholeblock/order": { "post": { "operationId": "wholeBlockOrder", "summary": "Order (wholeblock)", "description": "Requires a JSON body. Review the reference for validation and retry semantics.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WholeBlockOrderRequest" } } } }, "responses": { "200": { "description": "Application success OR failure; inspect success and any nested item results.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OrderResponse" }, { "$ref": "#/components/schemas/ApplicationError" } ] } } } }, "400": { "description": "Input validation or unsupported HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "500": { "description": "Unexpected server failure; mutation outcome may be unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "503": { "description": "Busy or unavailable service; reconcile mutations before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } }, "401": { "description": "Authentication required; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } } }, "403": { "description": "Access denied; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "429": { "description": "Per-process concurrency or database-pressure rejection; JSON code 20. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } } } } }, "/api/v1/wholeblock/cancel-order": { "post": { "operationId": "wholeBlockCancelOrder", "summary": "Cancel Order (wholeblock)", "description": "Requires a JSON body. Review the reference for validation and retry semantics.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "responses": { "200": { "description": "Application success OR failure; inspect success and any nested item results.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CancelItemsDataResponse" }, { "$ref": "#/components/schemas/ApplicationError" } ] } } } }, "400": { "description": "Input validation or unsupported HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "500": { "description": "Unexpected server failure; mutation outcome may be unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "503": { "description": "Busy or unavailable service; reconcile mutations before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } }, "401": { "description": "Authentication required; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } } }, "403": { "description": "Access denied; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "429": { "description": "Per-process concurrency or database-pressure rejection; JSON code 20. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } } } } }, "/api/v1/wholeblock/cancel-batch-orders": { "post": { "operationId": "wholeBlockCancelBatchOrders", "summary": "Cancel Batch Orders (wholeblock)", "description": "Requires a JSON body. Review the reference for validation and retry semantics.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelBatchRequest" } } } }, "responses": { "200": { "description": "Application success OR failure; inspect success and any nested item results.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CancelItemsDataResponse" }, { "$ref": "#/components/schemas/ApplicationError" } ] } } } }, "400": { "description": "Input validation or unsupported HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "500": { "description": "Unexpected server failure; mutation outcome may be unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "503": { "description": "Busy or unavailable service; reconcile mutations before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } }, "401": { "description": "Authentication required; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } } }, "403": { "description": "Access denied; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "429": { "description": "Per-process concurrency or database-pressure rejection; JSON code 20. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } } } } }, "/api/v1/wholeblock/cancel-all-orders": { "post": { "operationId": "wholeBlockCancelAllOrders", "summary": "Cancel All Orders (wholeblock)", "description": "Requires a JSON body. Review the reference for validation and retry semantics. WARNING: omitting/null/blank instrumentId cancels all instruments in this market family for the account. Both single-instrument and all-instruments scopes are intentional supported features. Omit instrumentId, or send null/blank, for all instruments of this market family in the account.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelAllRequest" } } } }, "responses": { "200": { "description": "Application success OR failure; inspect success and any nested item results.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CancelAllDataResponse" }, { "$ref": "#/components/schemas/ApplicationError" } ] } } } }, "400": { "description": "Input validation or unsupported HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "500": { "description": "Unexpected server failure; mutation outcome may be unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "503": { "description": "Busy or unavailable service; reconcile mutations before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } }, "401": { "description": "Authentication required; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } } }, "403": { "description": "Access denied; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "429": { "description": "Per-process concurrency or database-pressure rejection; JSON code 20. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } } } } }, "/api/v1/inclusion-preconf/order": { "post": { "operationId": "inclusionOrder", "summary": "Order (inclusion-preconf)", "description": "Requires a JSON body. Review the reference for validation and retry semantics.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InclusionOrderRequest" } } } }, "responses": { "200": { "description": "Application success OR failure; inspect success and any nested item results.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OrderResponse" }, { "$ref": "#/components/schemas/ApplicationError" } ] } } } }, "400": { "description": "Input validation or unsupported HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "500": { "description": "Unexpected server failure; mutation outcome may be unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "503": { "description": "Busy or unavailable service; reconcile mutations before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } }, "401": { "description": "Authentication required; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } } }, "403": { "description": "Access denied; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "429": { "description": "Per-process concurrency or database-pressure rejection; JSON code 20. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } } } } }, "/api/v1/inclusion-preconf/cancel-order": { "post": { "operationId": "inclusionCancelOrder", "summary": "Cancel Order (inclusion-preconf)", "description": "Requires a JSON body. Review the reference for validation and retry semantics.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "responses": { "200": { "description": "Application success OR failure; inspect success and any nested item results.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CancelItemsDataResponse" }, { "$ref": "#/components/schemas/ApplicationError" } ] } } } }, "400": { "description": "Input validation or unsupported HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "500": { "description": "Unexpected server failure; mutation outcome may be unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "503": { "description": "Busy or unavailable service; reconcile mutations before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } }, "401": { "description": "Authentication required; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } } }, "403": { "description": "Access denied; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "429": { "description": "Per-process concurrency or database-pressure rejection; JSON code 20. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } } } } }, "/api/v1/inclusion-preconf/cancel-batch-orders": { "post": { "operationId": "inclusionCancelBatchOrders", "summary": "Cancel Batch Orders (inclusion-preconf)", "description": "Requires a JSON body. Review the reference for validation and retry semantics.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelBatchRequest" } } } }, "responses": { "200": { "description": "Application success OR failure; inspect success and any nested item results.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CancelItemsDataResponse" }, { "$ref": "#/components/schemas/ApplicationError" } ] } } } }, "400": { "description": "Input validation or unsupported HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "500": { "description": "Unexpected server failure; mutation outcome may be unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "503": { "description": "Busy or unavailable service; reconcile mutations before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } }, "401": { "description": "Authentication required; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } } }, "403": { "description": "Access denied; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "429": { "description": "Per-process concurrency or database-pressure rejection; JSON code 20. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } } } } }, "/api/v1/inclusion-preconf/cancel-all-orders": { "post": { "operationId": "inclusionCancelAllOrders", "summary": "Cancel All Orders (inclusion-preconf)", "description": "Requires a JSON body. Review the reference for validation and retry semantics. WARNING: omitting/null/blank instrumentId cancels all instruments in this market family for the account. Both single-instrument and all-instruments scopes are intentional supported features. Omit instrumentId, or send null/blank, for all instruments of this market family in the account.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelAllRequest" } } } }, "responses": { "200": { "description": "Application success OR failure; inspect success and any nested item results.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CancelAllDataResponse" }, { "$ref": "#/components/schemas/ApplicationError" } ] } } } }, "400": { "description": "Input validation or unsupported HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "500": { "description": "Unexpected server failure; mutation outcome may be unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "503": { "description": "Busy or unavailable service; reconcile mutations before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } }, "401": { "description": "Authentication required; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } } }, "403": { "description": "Access denied; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "429": { "description": "Per-process concurrency or database-pressure rejection; JSON code 20. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } } } } }, "/api/v1/user/login": { "post": { "operationId": "requestLogin", "summary": "requestLogin", "description": "Form parameters are also accepted in the query string. Prefer form bodies for credential values. Verification sets x_auth_refresh_token via Set-Cookie; retain it. JWT timestamps use seconds. ", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "addr": { "type": "string" } }, "required": [ "addr" ] } } } }, "responses": { "200": { "description": "Application success OR failure; inspect success and any nested item results.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LoginDataResponse" }, { "$ref": "#/components/schemas/ApplicationError" } ] } } } }, "400": { "description": "Input validation or unsupported HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "500": { "description": "Unexpected server failure; mutation outcome may be unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "503": { "description": "Busy or unavailable service; reconcile mutations before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } }, "401": { "description": "Authentication required; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } } }, "403": { "description": "Access denied; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "429": { "description": "Per-process concurrency or database-pressure rejection; JSON code 20. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } } } } }, "/api/v1/user/login/verify": { "post": { "operationId": "verifyLogin", "summary": "verifyLogin", "description": "Form parameters are also accepted in the query string. Prefer form bodies for credential values. Verification sets x_auth_refresh_token via Set-Cookie; retain it. JWT timestamps use seconds. ", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "addr": { "type": "string" }, "nonceHash": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "addr", "nonceHash", "signature" ] } } } }, "responses": { "200": { "description": "Application success OR failure; inspect success and any nested item results.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthDataResponse" }, { "$ref": "#/components/schemas/ApplicationError" } ] } } }, "headers": { "Set-Cookie": { "description": "On successful verification, x_auth_refresh_token refresh credential. Retain securely.", "schema": { "type": "string" } } } }, "400": { "description": "Input validation or unsupported HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "500": { "description": "Unexpected server failure; mutation outcome may be unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "503": { "description": "Busy or unavailable service; reconcile mutations before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } }, "401": { "description": "Authentication required; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } } }, "403": { "description": "Access denied; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "429": { "description": "Per-process concurrency or database-pressure rejection; JSON code 20. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } } }, "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/user/login/refresh": { "post": { "operationId": "refreshLogin", "summary": "refreshLogin", "description": "Form parameters are also accepted in the query string. Prefer form bodies for credential values. Verification sets x_auth_refresh_token via Set-Cookie; retain it. JWT timestamps use seconds. A refresh credential is required from cookie OR parameter; User-Agent/session context must match.", "security": [], "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string" } } } } } }, "responses": { "200": { "description": "Application success OR failure; inspect success and any nested item results.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthDataResponse" }, { "$ref": "#/components/schemas/ApplicationError" } ] } } } }, "400": { "description": "Input validation or unsupported HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "500": { "description": "Unexpected server failure; mutation outcome may be unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "503": { "description": "Busy or unavailable service; reconcile mutations before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } }, "401": { "description": "Authentication required; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } } }, "403": { "description": "Access denied; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "429": { "description": "Per-process concurrency or database-pressure rejection; JSON code 20. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } } }, "parameters": [ { "in": "header", "name": "User-Agent", "required": true, "schema": { "type": "string" } }, { "in": "cookie", "name": "x_auth_refresh_token", "required": false, "schema": { "type": "string" }, "description": "A refresh credential is required from cookie OR form/query parameter. Cookie wins on refresh; logout rejects conflicts." } ] } }, "/api/v1/user/logout": { "post": { "operationId": "logout", "summary": "logout", "description": "Form parameters are also accepted in the query string. Prefer form bodies for credential values. Verification sets x_auth_refresh_token via Set-Cookie; retain it. JWT timestamps use seconds. Logout requires refresh cookie or parameter in addition to bearer.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string" } } } } } }, "responses": { "200": { "description": "Application success OR failure; inspect success and any nested item results.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/EmptySuccess" }, { "$ref": "#/components/schemas/ApplicationError" } ] } } } }, "400": { "description": "Input validation or unsupported HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "415": { "description": "Unsupported media type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } } }, "500": { "description": "Unexpected server failure; mutation outcome may be unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "503": { "description": "Busy or unavailable service; reconcile mutations before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } }, "401": { "description": "Authentication required; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } } }, "403": { "description": "Access denied; JSON code 1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." } } }, "429": { "description": "Per-process concurrency or database-pressure rejection; JSON code 20. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationError" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Server-generated correlation ID." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Minimum delay in seconds; configured default 1. Reconcile ambiguous mutations before replay." } } } }, "parameters": [ { "in": "cookie", "name": "x_auth_refresh_token", "required": false, "schema": { "type": "string" }, "description": "A refresh credential is required from cookie OR form/query parameter. Cookie wins on refresh; logout rejects conflicts." } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "ApplicationError": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "errorCode": { "type": "integer" }, "errorMsgKey": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "properties": { "requestId": { "type": "string", "description": "Server-generated ID on boundary errors; also sent in X-Request-ID." }, "retryAfterSeconds": { "type": "integer", "minimum": 1, "description": "Retry delay on service-generated 429/503; not permission to replay a mutation." } } } }, "required": [ "success", "errorCode" ] }, "EmptySuccess": { "type": "object", "properties": { "success": { "const": true, "type": "boolean" }, "data": { "type": "object" } }, "required": [ "success", "data" ] }, "AccessToken": { "type": "object", "properties": { "token": { "type": "string" }, "data": { "type": "object", "properties": { "header": { "type": "object" }, "payload": { "type": "object", "properties": { "iat": { "type": "integer", "format": "int64" }, "exp": { "type": "integer", "format": "int64" }, "access_type": { "type": "string" }, "user": { "type": "object" } } } }, "required": [ "header", "payload" ] } }, "required": [ "token", "data" ] }, "LoginData": { "type": "object", "properties": { "status": { "type": "string", "const": "verify" }, "eip712Message": { "type": "string", "description": "JSON-encoded EIP-712 object. Parse once before signing." }, "nonceHash": { "type": "string" } }, "required": [ "status", "eip712Message", "nonceHash" ] }, "AuthData": { "type": "object", "properties": { "user": { "type": "object", "additionalProperties": true, "description": "User/account fields are not fully modeled in this core subset." }, "accessToken": { "$ref": "#/components/schemas/AccessToken" } }, "required": [ "user", "accessToken" ] }, "CancelItem": { "type": "object", "properties": { "code": { "type": "integer", "description": "0 is success; inspect each item even when outer success is true." }, "errorMsg": { "type": "string" }, "accountId": { "type": "integer", "format": "int32", "description": "Account ID; omitted or zero is rejected by create-order validation." }, "orderId": { "type": "integer", "format": "int64" }, "clientOrderId": { "type": "string" } }, "required": [ "code", "errorMsg", "accountId" ] }, "CancelItemsData": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/CancelItem" } } }, "required": [ "orders" ] }, "CancelAllData": { "type": "object", "properties": { "code": { "type": "integer", "const": 0 } }, "required": [ "code" ] }, "LoginDataResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/LoginData" } }, "required": [ "success", "data" ] }, "AuthDataResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/AuthData" } }, "required": [ "success", "data" ] }, "CancelItemsDataResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/CancelItemsData" } }, "required": [ "success", "data" ] }, "CancelAllDataResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/CancelAllData" } }, "required": [ "success", "data" ] }, "WholeBlockOrderRequest": { "type": "object", "properties": { "accountId": { "type": "integer", "format": "int32", "description": "Account ID; omitted or zero is rejected by create-order validation." }, "instrumentId": { "type": "string", "description": "Canonical market selector. Do not send contradictory marketId/instrumentId values." }, "marketId": { "type": "integer", "format": "int64" }, "side": { "type": "boolean", "description": "Canonical true=buy, false=sell. Legacy numeric/string coercion is accepted by the server." }, "orderType": { "type": "integer", "enum": [ 1, 2, 3 ] }, "clientOrderId": { "type": "string", "pattern": "^[a-zA-Z0-9]{1,32}$", "maxLength": 32, "minLength": 1 }, "passive": { "type": "boolean", "default": false }, "price": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "Plain decimal string. Use decimal arithmetic; market constraints apply." }, "quantity": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "Ignored on this route: server fixes quantity to 1." } }, "required": [ "accountId", "side", "orderType", "clientOrderId" ], "anyOf": [ { "required": [ "instrumentId" ] }, { "required": [ "marketId" ], "properties": { "marketId": { "not": { "const": 0 } } } } ], "allOf": [ { "if": { "properties": { "orderType": { "enum": [ 2, 3 ] } }, "required": [ "orderType" ] }, "then": { "required": [ "price" ] } }, { "not": { "required": [ "orderType", "passive" ], "properties": { "orderType": { "const": 3 }, "passive": { "const": true } } } } ], "description": "Canonical request shape. Price for limit/FOK and inclusion quantity must be positive and meet market constraints. Do not submit output-only fields. Unknown input properties may be ignored by v1." }, "InclusionOrderRequest": { "type": "object", "properties": { "accountId": { "type": "integer", "format": "int32", "description": "Account ID; omitted or zero is rejected by create-order validation." }, "instrumentId": { "type": "string", "description": "Canonical market selector. Do not send contradictory marketId/instrumentId values." }, "marketId": { "type": "integer", "format": "int64" }, "side": { "type": "boolean", "description": "Canonical true=buy, false=sell. Legacy numeric/string coercion is accepted by the server." }, "orderType": { "type": "integer", "enum": [ 1, 2, 3 ] }, "clientOrderId": { "type": "string", "pattern": "^[a-zA-Z0-9]{1,32}$", "maxLength": 32, "minLength": 1 }, "passive": { "type": "boolean", "default": false }, "price": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "Plain decimal string. Use decimal arithmetic; market constraints apply." }, "quantity": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "Positive gas quantity; obey market bounds and step." } }, "required": [ "accountId", "side", "orderType", "clientOrderId", "quantity" ], "anyOf": [ { "required": [ "instrumentId" ] }, { "required": [ "marketId" ], "properties": { "marketId": { "not": { "const": 0 } } } } ], "allOf": [ { "if": { "properties": { "orderType": { "enum": [ 2, 3 ] } }, "required": [ "orderType" ] }, "then": { "required": [ "price" ] } }, { "not": { "required": [ "orderType", "passive" ], "properties": { "orderType": { "const": 3 }, "passive": { "const": true } } } } ], "description": "Canonical request shape. Price for limit/FOK and inclusion quantity must be positive and meet market constraints. Do not submit output-only fields. Unknown input properties may be ignored by v1." }, "OrderAcknowledgement": { "type": "object", "properties": { "accountId": { "type": "integer", "format": "int32", "description": "Account ID; omitted or zero is rejected by create-order validation." }, "instrumentId": { "type": "string", "description": "Canonical market selector. Do not send contradictory marketId/instrumentId values." }, "marketId": { "type": "integer", "format": "int64", "description": "Can remain 0 for instrument-only requests." }, "side": { "type": "boolean", "description": "Canonical true=buy, false=sell. Legacy numeric/string coercion is accepted by the server." }, "orderType": { "type": "integer", "enum": [ 1, 2, 3 ] }, "clientOrderId": { "type": "string", "pattern": "^[a-zA-Z0-9]{1,32}$", "maxLength": 32, "minLength": 1 }, "passive": { "type": "boolean", "default": false }, "price": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "Plain decimal string. Use decimal arithmetic; market constraints apply." }, "orderId": { "type": "integer", "format": "int64" }, "quantity": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "Plain decimal string. Use decimal arithmetic; market constraints apply." }, "fulfilled": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "Plain decimal string. Use decimal arithmetic; market constraints apply." }, "status": { "type": "integer" }, "source": { "type": "integer", "const": 1 }, "orderDate": { "type": "integer", "format": "int64", "description": "Unix epoch milliseconds." }, "preconfQuantity": { "type": "integer" }, "fees": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "May reflect request input; do not treat acknowledgement fees as authoritative." } }, "required": [ "orderId", "accountId", "marketId", "side", "orderType", "clientOrderId", "quantity", "status", "source", "orderDate", "passive" ] }, "OrderData": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/OrderAcknowledgement" } }, "required": [ "order" ] }, "OrderResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/OrderData" } }, "required": [ "success", "data" ] }, "CancelRequest": { "type": "object", "properties": { "accountId": { "type": "integer", "format": "int32", "description": "Account ID; omitted or zero is rejected by create-order validation." }, "instrumentId": { "type": "string", "minLength": 1, "pattern": "\\S" }, "clientOrderId": { "type": "string", "pattern": "^[a-zA-Z0-9]{1,32}$", "maxLength": 32, "minLength": 1 }, "orderId": { "type": "integer", "format": "int64" } }, "required": [ "accountId", "instrumentId" ], "oneOf": [ { "required": [ "clientOrderId" ], "not": { "required": [ "orderId" ] } }, { "required": [ "orderId" ], "not": { "required": [ "clientOrderId" ] } } ], "description": "Canonical request: exactly one non-null ID family. Runtime treats explicit null IDs like absence; use omission instead." }, "CancelBatchRequest": { "type": "object", "properties": { "accountId": { "type": "integer", "format": "int32", "description": "Account ID; omitted or zero is rejected by create-order validation." }, "instrumentId": { "type": "string", "minLength": 1, "pattern": "\\S" }, "clientOrderIds": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "pattern": "^[a-zA-Z0-9]{1,32}$", "maxLength": 32, "minLength": 1 } }, "orderIds": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "integer", "format": "int64" } } }, "required": [ "accountId", "instrumentId" ], "oneOf": [ { "required": [ "clientOrderIds" ], "not": { "required": [ "orderIds" ] } }, { "required": [ "orderIds" ], "not": { "required": [ "clientOrderIds" ] } } ], "description": "Canonical request: exactly one non-null ID family. Runtime treats explicit null IDs like absence; use omission instead." }, "CancelAllRequest": { "type": "object", "properties": { "accountId": { "type": "integer", "format": "int32", "description": "Account ID; omitted or zero is rejected by create-order validation." }, "instrumentId": { "type": [ "string", "null" ], "description": "Intentional scope selector: a nonblank value selects one instrument; omitted, null or blank selects all instruments of this market family for the specified account." } }, "required": [ "accountId" ] } } } }