{ "openapi": "3.0.0", "info": { "title": "x-gateway-external-api", "contact": {} }, "servers": [ { "url": "https://api.xgateway.tech/api/v2" } ], "paths": { "/balance/accounts/{accountId}": { "get": { "operationId": "ReadAccountBalanceAsync", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppSuccessResponse_AccountPublicResponse_" }, "examples": { "Single Account": { "value": { "data": { "type": "fiat", "accountId": "ff36a7a5-08fd-418a-a150-f6f2d36676a8", "accountLabel": "TRY Papara", "accountNumber": "TRY-ff36a7a5-TRY", "accountCurrency": "TRY", "referenceCurrency": "USD", "currency": "TRY", "balance": "1000.00", "balanceReferenceCurrency": "115.00", "withdrawableBalance": "950.00", "withdrawableBalanceReferenceCurrency": "109.25", "paymentMethod": "gateway5_papara", "isActive": true, "isWithdrawalAllowed": true }, "success": true } }, "Zero Balance": { "value": { "data": { "type": "crypto", "accountId": "abc739d2-3a33-4719-8f9a-b57f8c6e3257", "accountLabel": null, "accountNumber": "ETH-abc739d2-ETH", "accountCurrency": "ETH", "referenceCurrency": "USD", "currency": "ETH", "balance": "0", "balanceReferenceCurrency": "0", "withdrawableBalance": "0", "withdrawableBalanceReferenceCurrency": "0", "paymentMethod": "gateway0", "isActive": false, "isWithdrawalAllowed": false, "network": "ethereum", "minConfirmationBlock": 6, "fullConfirmationBlock": 8, "depositFullConfirmationThresholdReferenceCurrency": "10000", "depositManualReviewThresholdReferenceCurrency": "10000" }, "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppAuthenticationErrorResponse" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppErrorResponse" } } } } }, "description": "Retrieves balances and public details for a specific merchant account.\r\n\r\nThis endpoint returns an account with its associated balances, currencies,\r\npayment method, and other public-facing metadata.\r\n\r\n### Account fields\r\n- `accountId` *(string)*: Unique account identifier.\r\n- `accountLabel` *(string | null)*: Optional human-readable account label.\r\n- `accountNumber` *(string)*: Account number.\r\n- `accountCurrency` *(string)*: Currency in which the account balance is held.\r\n- `referenceCurrency` *(string)*: Reference currency used for reporting purposes\r\n (e.g. USD).\r\n- `currency` *(string)*: Operational currency. Deposits are typically made in this currency.\r\n- `balance` *(string)*: Current account balance.\r\n- `balanceReferenceCurrency` *(string)*: Current balance expressed in the reference currency.\r\n- `withdrawableBalance` *(string)*: Balance available for withdrawal.\r\n- `withdrawableBalanceReferenceCurrency` *(string)*: Withdrawable balance expressed in the reference currency.\r\n- `paymentMethod` *(string | null)*: Attached payment method code, if applicable.\r\n- `isActive` *(boolean)*: Indicates whether the account is active.\r\n- `isWithdrawalAllowed` *(boolean)*: Indicates whether withdrawals are allowed for this account.\r\n- `type` *(string)*: Account type. Possible values: `fiat`, `crypto`.\r\n- `network` *(string | null)*: Blockchain network for crypto accounts, if applicable.\r\n- `minConfirmationBlock` *(number | null)*: Minimum number of blocks required for a transaction\r\n to be considered confirmed.\r\n- `fullConfirmationBlock` *(number | null)*: Number of blocks required for a transaction\r\n to be considered fully confirmed.\r\n- `depositFullConfirmationThresholdReferenceCurrency` *(string | null)*:\r\n Threshold for full deposit confirmation in the reference currency. If a transaction\r\n exceeds this threshold, it must receive the full number of confirmation blocks.\r\n- `depositManualReviewThresholdReferenceCurrency` *(string | null)*:\r\n Threshold for manual deposit review in the reference currency. If a transaction\r\n exceeds this threshold, it must be manually reviewed by an XGateway admin.", "summary": "Get merchant account balances and details.", "tags": [ "Balance" ], "security": [ { "api_key": [] } ], "parameters": [ { "description": "- Unique identifier of the account.", "in": "path", "name": "accountId", "required": true, "schema": { "type": "string" } } ] } } }, "components": { "schemas": { "AppClientErrorResponseCode": { "type": "string", "enum": [ "bad_request", "db_violation", "unauthorized", "payment_required", "forbidden", "not_found", "method_not_allowed", "not_acceptable", "proxy_authentication_required", "request_timeout", "conflict", "db_unique_violation", "gone", "length_required", "precondition_failed", "payload_too_large", "uri_too_long", "unsupported_media_type", "range_not_satisfiable", "expectation_failed", "misdirected_request", "unprocessable_content", "db_non_null_violation", "locked", "failed_dependency", "upgrade_required", "precondition_required", "too_many_requests", "request_header_fields_too_large", "unavailable_for_legal_reasons" ], "nullable": false, "description": "The AppClientErrorResponseCode object contains all client error response codes." }, "AppServerErrorResponseCode": { "type": "string", "enum": [ "internal_server_error", "not_implemented", "bad_gateway", "service_unavailable", "gateway_timeout", "http_version_not_supported", "variant_also_negotiates", "insufficient_storage", "loop_detected", "not_extended", "network_authentication_required" ], "nullable": false, "description": "The AppServerErrorResponseCode object contains all server error response codes." }, "IAppError": { "description": "The IAppError interface represents an application error message.", "properties": { "code": { "anyOf": [ { "$ref": "#/components/schemas/AppClientErrorResponseCode" }, { "$ref": "#/components/schemas/AppServerErrorResponseCode" } ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "additionalProperties": false }, "AppErrorResponse": { "description": "The AppErrorResponse object contains general information about the error message.", "properties": { "success": { "type": "boolean", "default": false }, "errors": { "items": { "$ref": "#/components/schemas/IAppError" }, "type": "array" } }, "required": [ "success", "errors" ], "type": "object", "additionalProperties": false }, "AppAuthenticationErrorResponse": { "description": "The AppAuthenticationErrorResponse object contains general information about the authentication\r\nerror.", "properties": { "success": { "type": "boolean", "default": false }, "errors": { "items": { "$ref": "#/components/schemas/IAppError" }, "type": "array", "default": [ { "code": "unauthorized", "message": "You do not have permission to access this resource." } ] } }, "required": [ "success", "errors" ], "type": "object", "additionalProperties": false }, "AccountPublicType.fiat": { "enum": [ "fiat" ], "type": "string" }, "FiatAccountPublicResponse": { "properties": { "accountCurrency": { "type": "string" }, "accountId": { "type": "string" }, "accountLabel": { "type": "string", "nullable": true }, "accountNumber": { "type": "string" }, "balance": { "type": "string" }, "balanceReferenceCurrency": { "type": "string" }, "currency": { "type": "string" }, "paymentMethod": { "type": "string" }, "referenceCurrency": { "type": "string" }, "withdrawableBalance": { "type": "string" }, "withdrawableBalanceReferenceCurrency": { "type": "string" }, "isActive": { "type": "boolean" }, "isWithdrawalAllowed": { "type": "boolean" }, "type": { "$ref": "#/components/schemas/AccountPublicType.fiat" } }, "required": [ "accountCurrency", "accountId", "accountLabel", "accountNumber", "balance", "balanceReferenceCurrency", "currency", "paymentMethod", "referenceCurrency", "withdrawableBalance", "withdrawableBalanceReferenceCurrency", "isActive", "isWithdrawalAllowed", "type" ], "type": "object", "additionalProperties": false }, "AccountPublicType.crypto": { "enum": [ "crypto" ], "type": "string" }, "CryptoAccountPublicResponse": { "properties": { "accountCurrency": { "type": "string" }, "accountId": { "type": "string" }, "accountLabel": { "type": "string", "nullable": true }, "accountNumber": { "type": "string" }, "balance": { "type": "string" }, "balanceReferenceCurrency": { "type": "string" }, "currency": { "type": "string" }, "paymentMethod": { "type": "string" }, "referenceCurrency": { "type": "string" }, "withdrawableBalance": { "type": "string" }, "withdrawableBalanceReferenceCurrency": { "type": "string" }, "isActive": { "type": "boolean" }, "isWithdrawalAllowed": { "type": "boolean" }, "type": { "$ref": "#/components/schemas/AccountPublicType.crypto" }, "network": { "type": "string" }, "minConfirmationBlock": { "type": "number", "format": "double" }, "fullConfirmationBlock": { "type": "number", "format": "double" }, "depositFullConfirmationThresholdReferenceCurrency": { "type": "string", "nullable": true }, "depositManualReviewThresholdReferenceCurrency": { "type": "string", "nullable": true } }, "required": [ "accountCurrency", "accountId", "accountLabel", "accountNumber", "balance", "balanceReferenceCurrency", "currency", "paymentMethod", "referenceCurrency", "withdrawableBalance", "withdrawableBalanceReferenceCurrency", "isActive", "isWithdrawalAllowed", "type", "network", "minConfirmationBlock", "fullConfirmationBlock", "depositFullConfirmationThresholdReferenceCurrency", "depositManualReviewThresholdReferenceCurrency" ], "type": "object", "additionalProperties": false }, "AccountPublicResponse": { "anyOf": [ { "$ref": "#/components/schemas/FiatAccountPublicResponse" }, { "$ref": "#/components/schemas/CryptoAccountPublicResponse" } ] }, "AppSuccessResponse_AccountPublicResponse_": { "description": "The AppSuccessResponse object contains general information about the success execution.", "properties": { "success": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/AccountPublicResponse" } }, "required": [ "success", "data" ], "type": "object", "additionalProperties": false } }, "securitySchemes": { "api_key": { "in": "header", "name": "x-api-key", "type": "apiKey" } } } }