{
  "openapi": "3.1.0",
  "info": {
    "title": "GatePay Withdrawal & Wallet API",
    "version": "1.0.0",
    "description": "OpenAPI 3.1 specification for GatePay withdrawal and wallet APIs, based on the English withdrawal documentation. It covers batch withdrawals, withdrawal status query, supported chains by currency, total balance query, and withdrawal fee query."
  },
  "servers": [
    {
      "url": "https://openplatform.gateapi.io",
      "description": "Production"
    }
  ],
  "paths": {
    "/v1/pay/withdraw": {
      "post": {
        "tags": [
          "withdraw"
        ],
        "summary": "Place withdrawal order",
        "description": "Create a batch withdrawal order. The merchant submits one batch ID with multiple withdrawal sub-orders.",
        "operationId": "createWithdrawBatch",
        "parameters": [
          {
            "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Signature"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Timestamp"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Nonce"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WithdrawCreateRequest"
              },
              "examples": {
                "default": {
                  "summary": "Place a batch withdrawal order",
                  "value": {
                    "batch_id": "237394559478075350",
                    "channel_id": "123456",
                    "withdraw_list": [
                      {
                        "merchant_withdraw_id": "M137394559478075550",
                        "currency": "USDT",
                        "amount": "1",
                        "chain": "ETH",
                        "address": "0x1234567890abcdef",
                        "memo": "Payment for services-1",
                        "fee_type": 1
                      },
                      {
                        "merchant_withdraw_id": "M137394559478075551",
                        "currency": "USDT",
                        "amount": "0.001",
                        "chain": "ETH",
                        "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
                        "memo": "Payment for services-1",
                        "fee_type": 0
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Withdrawal batch created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WithdrawCreateResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful response",
                    "value": {
                      "status": "SUCCESS",
                      "code": "000000",
                      "errorMessage": "",
                      "data": {
                        "batch_id": "237394559478075550"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/pay/withdraw/query": {
      "post": {
        "tags": [
          "withdraw"
        ],
        "summary": "Query withdrawal order status",
        "description": "Query the status and details of a batch withdrawal order and its sub-orders by batch ID and detail status.",
        "operationId": "queryWithdrawBatch",
        "parameters": [
          {
            "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Signature"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Timestamp"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Nonce"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WithdrawQueryRequest"
              },
              "examples": {
                "default": {
                  "summary": "Query all sub-orders under a batch",
                  "value": {
                    "batch_id": "237394559478075555",
                    "detail_status": "ALL"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Withdrawal batch details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WithdrawQueryResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful response",
                    "value": {
                      "status": "SUCCESS",
                      "code": "000000",
                      "errorMessage": "",
                      "data": {
                        "batch_id": "237394559478075350",
                        "merchant_id": 10002,
                        "client_id": "mZ96D37oKk-HrWJc",
                        "status": "FAIL",
                        "create_time": 1726055849126,
                        "channel_id": "123456",
                        "withdraw_list": [
                          {
                            "id": 35,
                            "batch_id": "237394559478075350",
                            "merchant_id": 10002,
                            "suborder_id": "268830764354768896",
                            "chain": "ETH",
                            "address": "0x1234567890abcdef",
                            "currency": "USDT",
                            "amount": "1",
                            "fee": "0",
                            "tx_id": "",
                            "timestamp": 0,
                            "memo": "Payment for services-1",
                            "status": "FAIL",
                            "merchant_withdraw_id": "M137394559478075550",
                            "err_msg": "unexpected http code error",
                            "client_id": "mZ96D37oKk-HrWJc",
                            "create_time": 1726055848856,
                            "update_time": 1726055856011,
                            "channel_id": "123456",
                            "done_amount": "1"
                          },
                          {
                            "id": 36,
                            "batch_id": "237394559478075350",
                            "merchant_id": 10002,
                            "suborder_id": "268830764354768897",
                            "chain": "ETH",
                            "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
                            "currency": "USDT",
                            "amount": "0.001",
                            "fee": "0",
                            "tx_id": "",
                            "timestamp": 0,
                            "memo": "Payment for services-1",
                            "status": "FAIL",
                            "merchant_withdraw_id": "M137394559478075551",
                            "err_msg": "unexpected http code error",
                            "client_id": "mZ96D37oKk-HrWJc",
                            "create_time": 1726055848856,
                            "update_time": 1726055856010,
                            "channel_id": "123456",
                            "done_amount": "0.001"
                          }
                        ]
                      }
                    }
                  },
                  "emptyData": {
                    "summary": "Batch ID not found",
                    "value": {
                      "status": "SUCCESS",
                      "code": "000000",
                      "errorMessage": "",
                      "data": {
                        "batch_id": "237394559478075358",
                        "merchant_id": 0,
                        "client_id": "",
                        "status": "",
                        "create_time": 0,
                        "withdraw_list": []
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/pay/wallet/currency_chains": {
      "get": {
        "tags": [
          "wallet"
        ],
        "summary": "Query supported chains for a currency",
        "description": "Query supported blockchain networks and related configuration for a specific currency.",
        "operationId": "getCurrencyChains",
        "parameters": [
          {
            "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Signature"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Timestamp"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Nonce"
          },
          {
            "name": "currency",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Currency symbol to query, e.g. USDT, BTC."
          }
        ],
        "responses": {
          "200": {
            "description": "List of supported chains",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/CurrencyChain"
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Successful response",
                    "value": [
                      {
                        "chain": "ETH",
                        "name_cn": "以太坊ERC20",
                        "name_en": "ETH/ERC20",
                        "contract_address": "",
                        "is_disabled": 0,
                        "is_deposit_disabled": 0,
                        "is_withdraw_disabled": 0
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/pay/wallet/withdraw_status": {
      "get": {
        "tags": [
          "wallet"
        ],
        "summary": "Query withdrawal fee",
        "description": "Query withdrawal fee configuration and limits for a specific currency.",
        "operationId": "getWithdrawStatus",
        "parameters": [
          {
            "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Signature"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Timestamp"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Nonce"
          },
          {
            "name": "currency",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Specify currency name."
          }
        ],
        "responses": {
          "200": {
            "description": "Withdrawal fee details. \nNo handling fees are charged for withdrawals to a Gate addresss, whereas handling fees apply when withdrawingto a non-Gate address.\n- When you call the \"Query Withdrawal Fee\" interface, it retturns the handling fees required by the supported chains for the coin. Choose the chain you need.\n- Pay attention to the two parameters below:\n* [withdraw_fix_on_chains] refers to the fixed handling fee.\n* [withdraw_percent_on_chains] refers to the percentage-based handling fee (When you withdraw certain\nspecial coins, the fee is calculated as the withdrawal quantity rmultiplied by the percentage).\n- Withdrawal Handling Fee = Fixed Handling Fee + Fee Percentage >Withdrawal Quantity\n- At present, most common chains only charge a fixed handling feewhich is updated hourly.\n- Call the interface to check the handling fee every time you make awithdrawal. The handling fee is updated hourly.\n</Info>",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WithdrawStatus"
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Successful response",
                    "value": [
                      {
                        "currency": "GT",
                        "name": "GateToken",
                        "name_cn": "GateToken",
                        "deposit": "0",
                        "withdraw_percent": "0%",
                        "withdraw_fix": "0.01",
                        "withdraw_day_limit": "20000",
                        "withdraw_day_limit_remain": "20000",
                        "withdraw_amount_mini": "0.11",
                        "withdraw_eachtime_limit": "20000",
                        "withdraw_fix_on_chains": {
                          "BTC": "20",
                          "ETH": "15",
                          "TRX": "0",
                          "EOS": "2.5"
                        },
                        "withdraw_percent_on_chains": {
                          "ETH": "0%",
                          "GTEVM": "0%"
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/pay/wallet/withdrawals": {
      "get": {
        "tags": [
          "wallet"
        ],
        "summary": "Query Withdrawal Records",
        "description": "Query account withdrawal records list based on filter criteria.",
        "operationId": "getWithdrawals",
        "parameters": [
          {
            "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Signature"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Timestamp"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Nonce"
          },
          {
            "name": "currency",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Specify currency to query, returns all currencies if empty."
          },
          {
            "name": "withdraw_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Withdrawal record ID (starts with 'w', e.g. w1879219868), queries single record if specified"
          },
          {
            "name": "asset_class",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "SPOT",
                "PILOT"
              ]
            },
            "description": "Currency type (Main/Pilot zone), empty by default. Values: SPOT, PILOT."
          },
          {
            "name": "withdraw_order_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "User-defined withdrawal order number for specific record query"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            },
            "description": "Start timestamp (Unix) units in seconds, defaults to last 7 days. Query time range cannot exceed 30 days."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64"
            },
            "description": "End timestamp (Unix) units in seconds, defaults to current time."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Maximum number of records to return."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Return record offset (starts from 0)."
          }
        ],
        "responses": {
          "200": {
            "description": "Withdrawal records list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WithdrawalRecord"
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Success response",
                    "value": [
                      {
                        "id": "w1879219868",
                        "currency": "USDT",
                        "address": "THISISTESTADDRESSFORGATEPAY",
                        "amount": "4.023",
                        "fee": "0",
                        "txid": "Internal transaction 260594131",
                        "chain": "BSC",
                        "timestamp": "1745220149",
                        "status": "DONE",
                        "withdraw_order_id": "202504211521368538928",
                        "block_number": "1000",
                        "fail_reason": "",
                        "type": "appbankgp",
                        "timestamp2": "1745220149",
                        "memo": ""
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/pay/batch/transfer": {
      "post": {
        "tags": [
          "reward-distribution"
        ],
        "summary": "Create merchant batch transfer",
        "description": "Create a batch transfer order from a merchant to multiple users.",
        "operationId": "createMerchantBatchTransfer",
        "parameters": [
          {
            "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Signature"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Timestamp"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Nonce"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-On-Behalf-Of-Optional"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RewardDistributionCreateRequest"
              },
              "examples": {
                "default": {
                  "summary": "Default example",
                  "value": {
                    "batchId": "237394559478075550",
                    "bizscene": "DIRECT_TRANSFER",
                    "merchant_batch_no": "RB202606300001",
                    "name": "June Reward Distribution",
                    "description": "monthly incentive",
                    "batchorderList": [
                      {
                        "user_id": 100001,
                        "amount": "12.5",
                        "currency": "USDT",
                        "rewardId": "reward_001"
                      },
                      {
                        "user_id": 100002,
                        "amount": "8.8",
                        "currency": "USDT",
                        "rewardId": "reward_002"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch transfer creation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RewardDistributionCreateResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Created successfully",
                    "value": {
                      "status": "SUCCESS",
                      "code": "000000",
                      "errorMessage": "",
                      "data": {
                        "merchant_batch_no": "RB202606300001",
                        "batch_id": "237394559478075550"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/pay/batch/transfer/query": {
      "post": {
        "tags": [
          "reward-distribution"
        ],
        "summary": "Query merchant batch transfer order",
        "description": "Query a merchant batch transfer order and its sub-order statuses by batch_id or merchant_batch_no.",
        "operationId": "queryMerchantBatchTransfer",
        "parameters": [
          {
            "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Signature"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Timestamp"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-Nonce"
          },
          {
            "$ref": "#/components/parameters/X-GatePay-On-Behalf-Of-Optional"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RewardDistributionQueryRequest"
              },
              "examples": {
                "default": {
                  "summary": "Default example",
                  "value": {
                    "merchant_batch_no": "RB202606300001",
                    "detail_status": "ALL"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch transfer order details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RewardDistributionQueryResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Queried successfully",
                    "value": {
                      "status": "SUCCESS",
                      "code": "000000",
                      "errorMessage": "",
                      "data": {
                        "batch_id": "237394559478075550",
                        "merchant_id": 10002,
                        "merchant_batch_no": "RB202606300001",
                        "status": "SUCCESS",
                        "channel_id": "123456",
                        "orders_list": [
                          {
                            "receiver_id": 100001,
                            "amount": "12.5",
                            "currency": "USDT",
                            "status": "SUCCESS",
                            "reward_id": "reward_001",
                            "transaction_id": "0xabc123",
                            "create_time": 1751263200000,
                            "channel_id": "123456"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "WithdrawCreateRequest": {
        "type": "object",
        "description": "Request body for placing a batch withdrawal order.",
        "properties": {
          "batch_id": {
            "type": "string",
            "description": "A unique ID generated by the merchant, composed of uppercase and lowercase letters, numbers, and underscores, max length 32 characters."
          },
          "withdraw_list": {
            "type": "array",
            "description": "Details of each withdrawal sub-order.",
            "items": {
              "$ref": "#/components/schemas/WithdrawItem"
            }
          },
          "channel_id": {
            "type": "string",
            "description": "Client name."
          }
        },
        "required": [
          "batch_id",
          "withdraw_list"
        ]
      },
      "RewardDistributionCreateRequest": {
        "type": "object",
        "description": "Request body for creating a merchant batch transfer order.",
        "properties": {
          "batchId": {
            "type": "string",
            "description": "Internal batch correlation ID used to associate the batch record with its sub-orders. Keep it unique within the merchant account. It may use the same value as `merchant_batch_no`."
          },
          "bizscene": {
            "type": "string",
            "description": "Business scenario identifier. This endpoint currently supports only `DIRECT_TRANSFER`.",
            "enum": [
              "DIRECT_TRANSFER"
            ]
          },
          "merchant_batch_no": {
            "type": "string",
            "description": "Merchant-side business batch number used for request idempotency and merchant queries. It must be unique on the merchant side."
          },
          "name": {
            "type": "string",
            "description": "Display name of the batch transfer."
          },
          "description": {
            "type": "string",
            "description": "Description of the batch transfer."
          },
          "batchorderList": {
            "type": "array",
            "description": "List of transfer sub-orders.",
            "items": {
              "$ref": "#/components/schemas/RewardDistributionOrderItem"
            }
          },
          "channelId": {
            "type": "string",
            "description": "Channel ID, optional."
          },
          "is_coupon": {
            "type": "boolean",
            "description": "Whether this is a coupon scenario. Optional, default is false."
          }
        },
        "required": [
          "batchId",
          "bizscene",
          "merchant_batch_no",
          "batchorderList"
        ]
      },
      "RewardDistributionOrderItem": {
        "type": "object",
        "description": "Sub-order item in a merchant batch transfer request.",
        "properties": {
          "user_id": {
            "type": "integer",
            "format": "int64",
            "description": "Receiver user ID."
          },
          "amount": {
            "type": "string",
            "description": "Transfer amount."
          },
          "currency": {
            "type": "string",
            "description": "Currency of the sub-order. The sub-order currency must match the main order currency."
          },
          "rewardId": {
            "type": "string",
            "description": "Merchant-generated unique sub-order ID. Only letters (A-Z, a-z), digits, and underscores are allowed. Maximum length: 32 characters."
          }
        },
        "required": [
          "user_id",
          "amount",
          "currency",
          "rewardId"
        ]
      },
      "RewardDistributionCreateResponse": {
        "type": "object",
        "description": "Response body for creating a merchant batch transfer order.",
        "properties": {
          "status": {
            "type": "string",
            "description": "API response result, SUCCESS or FAIL."
          },
          "code": {
            "type": "string",
            "description": "Response error code."
          },
          "errorMessage": {
            "type": "string",
            "description": "Error description."
          },
          "data": {
            "$ref": "#/components/schemas/RewardDistributionCreateResult"
          }
        },
        "required": [
          "status",
          "code"
        ]
      },
      "RewardDistributionCreateResult": {
        "type": "object",
        "properties": {
          "merchant_batch_no": {
            "type": "string",
            "description": "Merchant batch number."
          },
          "batch_id": {
            "type": "string",
            "description": "Internal batch correlation ID provided in the request."
          }
        }
      },
      "RewardDistributionQueryRequest": {
        "type": "object",
        "description": "Request body for querying a merchant batch transfer order.",
        "properties": {
          "batch_id": {
            "type": "string",
            "description": "GatePay batch ID. Either batch_id or merchant_batch_no can be provided. When both are provided, batch_id is used."
          },
          "merchant_batch_no": {
            "type": "string",
            "description": "Merchant batch number. Either merchant_batch_no or batch_id can be provided. When both are provided, batch_id is used."
          },
          "detail_status": {
            "type": "string",
            "description": "Sub-order status filter: ALL, PROCESSING, SUCCESS, FAIL."
          }
        }
      },
      "RewardDistributionQueryResponse": {
        "type": "object",
        "description": "Response body for querying a merchant batch transfer order.",
        "properties": {
          "status": {
            "type": "string",
            "description": "API response result, SUCCESS or FAIL."
          },
          "code": {
            "type": "string",
            "description": "Response error code."
          },
          "errorMessage": {
            "type": "string",
            "description": "Error description."
          },
          "data": {
            "$ref": "#/components/schemas/RewardDistributionQueryResult"
          }
        },
        "required": [
          "status",
          "code"
        ]
      },
      "RewardDistributionQueryResult": {
        "type": "object",
        "properties": {
          "batch_id": {
            "type": "string",
            "description": "Batch ID."
          },
          "merchant_id": {
            "type": "integer",
            "format": "int64",
            "description": "Merchant ID."
          },
          "merchant_batch_no": {
            "type": "string",
            "description": "Merchant batch number."
          },
          "status": {
            "type": "string",
            "description": "Batch status, such as PROCESSING, SUCCESS, or FAIL."
          },
          "channel_id": {
            "type": "string",
            "description": "Channel ID."
          },
          "orders_list": {
            "type": "array",
            "description": "List of sub-orders.",
            "items": {
              "$ref": "#/components/schemas/RewardDistributionOrderResult"
            }
          }
        }
      },
      "RewardDistributionOrderResult": {
        "type": "object",
        "properties": {
          "receiver_id": {
            "type": "integer",
            "format": "int64",
            "description": "Receiver user ID."
          },
          "amount": {
            "type": "string",
            "description": "Transfer amount."
          },
          "currency": {
            "type": "string",
            "description": "Currency."
          },
          "status": {
            "type": "string",
            "description": "Sub-order status: PROCESSING, SUCCESS, or FAIL."
          },
          "reward_id": {
            "type": "string",
            "description": "Merchant-generated unique sub-order ID. Only letters (A-Z, a-z), digits, and underscores are allowed. Maximum length: 32 characters."
          },
          "transaction_id": {
            "type": "string",
            "description": "Transaction ID."
          },
          "create_time": {
            "type": "integer",
            "format": "int64",
            "description": "Creation time."
          },
          "channel_id": {
            "type": "string",
            "description": "Channel ID."
          }
        }
      },
      "WithdrawItem": {
        "type": "object",
        "description": "Details of a withdrawal sub-order.",
        "properties": {
          "merchant_withdraw_id": {
            "type": "string",
            "description": "Unique ID for the sub-order generated by the merchant, composed of uppercase and lowercase letters, numbers, and underscores, max length 32 characters."
          },
          "amount": {
            "type": "string",
            "format": "decimal",
            "description": "Withdrawal amount per order. Must be greater than 0. Accepts string or number; more than 8 decimal places are truncated to 8."
          },
          "currency": {
            "type": "string",
            "description": "Withdrawal currency."
          },
          "chain": {
            "type": "string",
            "description": "Blockchain network."
          },
          "address": {
            "type": "string",
            "description": "Withdrawal address."
          },
          "memo": {
            "type": "string",
            "description": "Transfer memo. Optional; when provided, max length is 128. Some chains (e.g. TON) may require it at business level; filling when unused may cause failure."
          },
          "fee_type": {
            "type": "integer",
            "description": "Withdrawal Fee Charge Methods:\n*Internal Charge: The fee is deducted directly from the withdrawal amount. The user receives the withdrawal amount minus the fee.\n*External Charge: The fee is deducted from the account balance. The user receives the full withdrawal amount.\n*When External Charge (main account is charged) is selected, the withdrawal fee for the sub-account is deducted from the main account balance.\nDefault Behavior:\nIf unspecified, the default method is Internal Charge.\nType Enumeration:\n0 – Internal Charge\n1 – External Charge\n2 – External Charge (main account is charged)"
          }
        },
        "required": [
          "merchant_withdraw_id",
          "amount",
          "currency",
          "chain",
          "address",
          "fee_type"
        ]
      },
      "WithdrawCreateResponse": {
        "type": "object",
        "description": "Response body for placing a batch withdrawal order.",
        "properties": {
          "status": {
            "type": "string",
            "description": "API response result, SUCCESS or FAIL."
          },
          "code": {
            "type": "string",
            "description": "Response error code."
          },
          "errorMessage": {
            "type": "string",
            "description": "Error description."
          },
          "data": {
            "type": "object",
            "properties": {
              "batch_id": {
                "type": "string",
                "description": "Unique batch ID generated by the merchant."
              }
            }
          }
        },
        "required": [
          "status",
          "code"
        ]
      },
      "WithdrawQueryRequest": {
        "type": "object",
        "description": "Request body for querying batch withdrawal status.",
        "properties": {
          "batch_id": {
            "type": "string",
            "description": "Unique batch ID generated by the merchant at /v1/pay/withdraw."
          },
          "detail_status": {
            "type": "string",
            "description": "Query status of sub-orders  <br> ALL: all sub-orders <br>INIT ：new added sub-orders <br>PENDING: pending sub-orders <br>PROCESSING: submitted withdrawal request, pending confirmation <br>CHECK: in review <br>FAIL: failed sub-orders <br>DONE: successful sub-orders."
          }
        },
        "required": [
          "batch_id",
          "detail_status"
        ]
      },
      "WithdrawQueryResponse": {
        "type": "object",
        "description": "Response body for querying batch withdrawal status.",
        "properties": {
          "status": {
            "type": "string",
            "description": "Main order status: INIT (newly created order), PROCESSING (newly created payout order is in processing), PARTIAL (partially successful), FAIL (fully failed), SUCCESS (fully successful)"
          },
          "code": {
            "type": "string",
            "description": "Error code"
          },
          "errorMessage": {
            "type": "string",
            "description": "Error message"
          },
          "data": {
            "type": "object",
            "description": "Batch withdrawal details",
            "properties": {
              "batch_id": {
                "type": "string",
                "description": "Batch ID."
              },
              "merchant_id": {
                "type": "integer",
                "format": "int64",
                "description": "Merchant ID."
              },
              "client_id": {
                "type": "string",
                "description": "Client ID."
              },
              "status": {
                "type": "string",
                "description": "Main order status: INIT (newly created order), PROCESSING (newly created payout order is in processing), PARTIAL (partially successful), FAIL (fully failed), SUCCESS (fully successful)."
              },
              "create_time": {
                "type": "integer",
                "format": "int64",
                "description": "Main order creation time."
              },
              "channel_id": {
                "type": "string",
                "description": "Customer channel name."
              },
              "withdraw_list": {
                "type": "array",
                "description": "Sub-order information.",
                "items": {
                  "$ref": "#/components/schemas/WithdrawSubOrder"
                }
              }
            }
          }
        },
        "required": [
          "status",
          "code"
        ]
      },
      "WithdrawSubOrder": {
        "type": "object",
        "description": "Details of a withdrawal sub-order.",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Record ID."
          },
          "batch_id": {
            "type": "string",
            "description": "Merchant batch withdrawal ID."
          },
          "merchant_id": {
            "type": "integer",
            "format": "int64",
            "description": "Merchant ID."
          },
          "channel_id": {
            "type": "string",
            "description": "Customer channel name."
          },
          "suborder_id": {
            "type": "string",
            "description": "Sub-order ID generated by GatePay."
          },
          "chain": {
            "type": "string",
            "description": "Blockchain network."
          },
          "address": {
            "type": "string",
            "description": "Withdrawal address."
          },
          "currency": {
            "type": "string",
            "description": "Currency."
          },
          "amount": {
            "type": "string",
            "format": "decimal",
            "description": "Initiated withdrawal amount"
          },
          "fee": {
            "type": "string",
            "format": "decimal",
            "description": "Fee amount."
          },
          "tx_id": {
            "type": "string",
            "description": "Blockchain transaction hash."
          },
          "timestamp": {
            "type": "integer",
            "format": "int64",
            "description": "Deposit/withdrawal operation time."
          },
          "memo": {
            "type": "string",
            "description": "Transfer memo and other note information."
          },
          "status": {
            "type": "string",
            "description": "Sub-order status: INIT (newly created sub-order), PENDING (order created, pending processing), PROCESSING (order is being processed), CHECK (under review), FAIL (withdrawal failed), DONE (withdrawal successful)"
          },
          "merchant_withdraw_id": {
            "type": "string",
            "description": "Merchant withdrawal ID."
          },
          "err_msg": {
            "type": "string",
            "description": "Reason for withdrawal failure."
          },
          "create_time": {
            "type": "integer",
            "format": "int64",
            "description": "Creation time."
          },
          "update_time": {
            "type": "integer",
            "format": "int64",
            "description": "Update time."
          },
          "fee_type": {
            "type": "integer",
            "description": "0 - Internal Charge\n1 - External Charge\n2 - External Charge (main account is charged)"
          },
          "done_amount": {
            "type": "string",
            "format": "decimal",
            "description": "Actual received amount."
          }
        }
      },
      "CurrencyChain": {
        "type": "object",
        "description": "Supported chain configuration for a currency.",
        "properties": {
          "chain": {
            "type": "string",
            "description": "Blockchain network name (e.g. ERC20, TRC20, BEP20)."
          },
          "name_cn": {
            "type": "string",
            "description": "Chinese name of blockchain (e.g. Ethereum for Ethereum)."
          },
          "name_en": {
            "type": "string",
            "description": "English name of blockchain (e.g. Ethereum, Tron)."
          },
          "contract_address": {
            "type": "string",
            "description": "Smart contract address (empty string for native coins like BTC, ETH)."
          },
          "is_disabled": {
            "type": "integer",
            "description": "Global disable status: 0 - enabled, 1 - disabled."
          },
          "is_deposit_disabled": {
            "type": "integer",
            "description": "Deposit function status: 0 - enabled, 1 - disabled."
          },
          "is_withdraw_disabled": {
            "type": "integer",
            "description": "Withdrawal function status: 0 - enabled, 1 - disabled."
          }
        }
      },
      "TotalBalanceResponse": {
        "type": "object",
        "description": "Response body for querying total balance of personal account.",
        "properties": {
          "total": {
            "$ref": "#/components/schemas/BalanceSummary"
          },
          "details": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/BalanceSummary"
            },
            "description": "Account type details. key is Account type."
          }
        }
      },
      "BalanceSummary": {
        "type": "object",
        "description": "Total account balance converted to target currency.",
        "properties": {
          "currency": {
            "type": "string",
            "description": "Target currency."
          },
          "amount": {
            "type": "string",
            "description": "Total balance amount."
          },
          "unrealised_pnl": {
            "type": "string",
            "description": "Unrealized PnL total (only appears for futures/options/delivery/total accounts)."
          },
          "borrowed": {
            "type": "string",
            "description": "Total margin borrowing (only appears for margin/cross_margin accounts)."
          }
        }
      },
      "WithdrawStatus": {
        "type": "object",
        "description": "Withdrawal fee and limit configuration for a currency.",
        "properties": {
          "currency": {
            "type": "string",
            "description": "Currency symbol, e.g. BTC, ETH."
          },
          "name": {
            "type": "string",
            "description": "Currency name (e.g. Bitcoin, Ethereum)."
          },
          "name_cn": {
            "type": "string",
            "description": "Chinese name of currency (e.g. Bitcoin, Ethereum)."
          },
          "deposit": {
            "type": "string",
            "description": "Deposit fee (usually \"0\" as string)."
          },
          "withdraw_percent": {
            "type": "string",
            "description": "Withdrawal fee percentage, e.g. \"0.1\" means 0.1%."
          },
          "withdraw_fix": {
            "type": "string",
            "description": "Fixed withdrawal fee, e.g. \"0.0005\"."
          },
          "withdraw_day_limit": {
            "type": "string",
            "description": "Daily withdrawal limit (maximum total amount per day)."
          },
          "withdraw_amount_mini": {
            "type": "string",
            "description": "Minimum withdrawal amount (single withdrawal cannot be lower than this, the value is 10 for USDT_TRX, for all other currencies, it is defined by the value provided by the API)."
          },
          "withdraw_day_limit_remain": {
            "type": "string",
            "description": "Remaining daily withdrawal limit (still available amount for today)."
          },
          "withdraw_eachtime_limit": {
            "type": "string",
            "description": "Maximum single withdrawal amount (cannot exceed this per transaction)."
          },
          "withdraw_fix_on_chains": {
            "type": "object",
            "description": "Fixed withdrawal fees per chain (property: chain name, value: fee string).",
            "additionalProperties": {
              "type": "string"
            }
          },
          "withdraw_percent_on_chains": {
            "type": "object",
            "description": "Percentage withdrawal fees per chain (property: chain name, value: percentage string).",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "WithdrawalRecord": {
        "type": "object",
        "description": "Withdrawal record details.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Transaction record ID."
          },
          "txid": {
            "type": "string",
            "description": "Blockchain transaction hash"
          },
          "block_number": {
            "type": "string",
            "description": "Block number"
          },
          "withdraw_order_id": {
            "type": "string",
            "description": "Client order ID (max 32 chars, only allows numbers/letters/_/-/.)."
          },
          "timestamp": {
            "type": "string",
            "description": "Operation time (Unix timestamp in seconds)."
          },
          "amount": {
            "type": "string",
            "description": "Amount of currency."
          },
          "fee": {
            "type": "string",
            "description": "Fee amount."
          },
          "currency": {
            "type": "string",
            "description": "Currency name."
          },
          "address": {
            "type": "string",
            "description": "Withdrawal address."
          },
          "fail_reason": {
            "type": "string",
            "description": "Failure reason (only when status = CANCEL)."
          },
          "timestamp2": {
            "type": "string",
            "description": "Final status time: CANCEL - Cancellation time; DONE (block_number>0) - Success time."
          },
          "memo": {
            "type": "string",
            "description": "Transaction memo/notes."
          },
          "status": {
            "type": "string",
            "description": "Transaction status: DONE (Completed, block_number > 0 means on-chain confirmed), CANCEL (Cancelled), REQUEST (Requesting), MANUAL (Pending manual review), BCODE (Top-up code operation), EXTPEND (Sent awaiting confirmation), FAIL (On-chain failure awaiting confirmation), INVALID (Invalid order), VERIFY (Verifying), PROCES (Processing), PEND (Processing), DMOVE (Pending manual review), REVIEW (Under review)."
          },
          "chain": {
            "type": "string",
            "description": "Withdrawal chain name."
          }
        }
      },
      "CommonErrorResponse": {
        "type": "object",
        "description": "Common error response structure, aligned with the response format in the documentation.",
        "properties": {
          "status": {
            "type": "string",
            "description": "API response result, SUCCESS or FAIL."
          },
          "code": {
            "type": "string",
            "description": "Response error code."
          },
          "label": {
            "type": "string",
            "description": "Error name."
          },
          "errorMessage": {
            "type": "string",
            "description": "Error description."
          },
          "data": {
            "description": "Business response data, may be empty.",
            "nullable": true
          }
        }
      }
    },
    "parameters": {
      "X-GatePay-Certificate-ClientId": {
        "name": "X-GatePay-Certificate-ClientId",
        "in": "header",
        "required": true,
        "description": "The clientId assigned when the merchant registers an application in the Gate merchant console.",
        "schema": {
          "type": "string",
          "example": "4186d0c6-6a35-55a9-8dc6-5312769dbff8"
        }
      },
      "X-GatePay-Signature": {
        "name": "X-GatePay-Signature",
        "in": "header",
        "required": true,
        "description": "Request signature. GatePay uses this signature to verify whether the request is valid.",
        "schema": {
          "type": "string"
        }
      },
      "X-GatePay-Timestamp": {
        "name": "X-GatePay-Timestamp",
        "in": "header",
        "required": true,
        "description": "Millisecond timestamp; the difference from server time must not exceed 30 seconds.",
        "schema": {
          "type": "string",
          "example": "1672905655498"
        }
      },
      "X-GatePay-Nonce": {
        "name": "X-GatePay-Nonce",
        "in": "header",
        "required": true,
        "description": "Random string. Must comply with HTTP header rules; recommended length is within 32 characters, composed of digits and letters.",
        "schema": {
          "type": "string",
          "example": "9578"
        }
      },
      "X-GatePay-On-Behalf-Of-Optional": {
        "name": "X-GatePay-On-Behalf-Of",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Optional delegated-subject header. Pass the initiating account ID only when an institution-delegated context needs to be identified; otherwise this header can be omitted."
      }
    }
  }
}