Private HTTP API V4 for Main balance changes

Base URL is https://whitebit.com (opens in a new tab)

Endpoint example: https://whitebit.com/api/v4/{endpoint} (opens in a new tab)

All endpoints return time in Unix-time format.

All endpoints return either a JSON object or array.

For receiving responses from API calls please use http method POST

Error messages V4 format

{
  "code": 0,
  "message": "MESSAGE",
  "errors": {
    "PARAM1": ["MESSAGE"],
    "PARAM2": ["MESSAGE"]
  }
}

Main balance

[POST] /api/v4/main-account/balance

This endpoint retrieves the main balance by currency ticker or all balances.

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
tickerStringNoCurrency's ticker. Example: BTC

Request BODY raw:

{
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response:

Available statuses:

  • Status 200
  • Status 400 if request validation failed
{
    "BSV": {
        "main_balance": "0"     // main balance volume of BSV
    },
    "BTC": {
        "main_balance": "0"     // main balance volume of BTC
    },
    "BTG": {
        "main_balance": "0"     // main balance volume of BTG
    },
    "BTT": {
        "main_balance": "0"     // main balance volume of BTT
    },
    "XLM": {
        "main_balance": "36.48" // main balance volume of XLM
    },
    "currecty_ticker": {...}
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "ticker": ["The selected ticker is invalid."]
  }
}
___

Get cryptocurrency deposit address

[POST] /api/v4/main-account/address

This endpoint retrieves a deposit address of the cryptocurrency.

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
tickerStringYesCurrencies ticker. Example: BTC ⚠ Currency ticker should not be fiat and it's "can_deposit" status must be "true". You can find this status in https://whitebit.com/api/v4/public/assets (opens in a new tab) respsonse.
networkStringYes, if currency is multinetworkCryptocurrency network. ⚠ If currency has multiple networks like USDT - you need to specify network to be used. You can find ticker networks list in “networks” field from response https://whitebit.com/api/v4/public/assets (opens in a new tab).

Request BODY raw:

{
  "ticker": "BTC",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Request BODY (for multinetwork currency) raw:

{
  "ticker": "USDT",
  "network": "ERC20",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response: Available statuses:

  • Status 200
  • Status 400 if request validation failed
  • Status 503 if service temporary unavailable
{
  "account": {
    "address": "GDTSOI56XNVAKJNJBLJGRNZIVOCIZJRBIDKTWSCYEYNFAZEMBLN75RMN", // deposit address
    "memo": "48565488244493"                                               // memo if currency requires memo
  },
  "required": {
    "fixedFee": "0",  // fixed deposit fee
    "flexFee": {      // flexible fee - is fee that use percent rate
      "maxFee": "0",  // maximum fixed fee that you will pay
      "minFee": "0",  // minimum fixed fee that you will pay
      "percent": "0"  // percent of deposit that you will pay
    },
    "maxAmount": "0", // max amount of deposit that can be accepted by exchange - if you deposit more than that number, it won't be accepted by exchange
    "minAmount": "1"  // min amount of deposit that can be accepted by exchange - if you will deposit less than that number, it won't be accepted by exchange
  }
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "ticker": ["The selected ticker is invalid."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "network": ["The selected network is invalid."]
  }
}
{
  "code": 1,
  "message": "Inner validation failed",
  "errors": {
    "ticker": ["Currency is not depositable"]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "ticker": ["Fiat deposits are available only on the website"]
  }
}

Get fiat deposit address

[POST] /api/v4/main-account/fiat-deposit-url

This endpoint retrieves a deposit url of the fiat invoice. Please, pay attention that this endpoint works on demand. It means that you need to contact WhiteBIT support and provide your API key to get access to this functionality.

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
tickerStringYesCurrencies ticker. Example: UAH ⚠ Currencies ticker should be: fiat and has "can_deposit" status must be "true". Use this url (opens in a new tab) to know more about currency.
providerStringYesFiat currency provider. Example: VISAMASTER ⚠ Currency provider should be taken from https://whitebit.com/api/v4/public/assets (opens in a new tab) response.
amountNumeric StringYesDeposit amount.
uniqueIdStringYesUnique transaction identifier on client's side.
customer.firstNameStringYes, if currency USD or EUR with VISAMASTER providerCustomer billing first name
customer.lastNameStringYes, if currency USD or EUR with VISAMASTER providerCustomer billing last name
customer.emailStringYes, if currency USD or EUR with VISAMASTER providerCustomer billing email
successLinkStringNoCustomer will be redirected to this URL by acquiring provider after success deposit. To activate this feature, please contact support
failureLinkStringNoCustomer will be redirected to this URL in case of fail or rejection on acquiring provider side. To activate this feature, please contact support
returnLinkStringNoCustomer will be redirected to the URL defined if selects 'back' option after from the payment success or failure page. To activate this feature, define desired link. If not populated, option 'back' won't be displayed

Request BODY raw:

{
  "ticker": "UAH",
  "provider": "VISAMASTER",
  "amount": "100",
  "uniqueId": "{{generateID}}",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Request BODY with customer fields raw:

{
  "ticker": "UAH",
  "provider": "VISAMASTER",
  "amount": "100",
  "uniqueId": "{{generateID}}",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john_doe@email.com"
  },
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response: Available statuses:

  • Status 200
  • Status 400 if request validation failed
  • Status 503 if service temporary unavailable
{
  "url": "https://someaddress.com" // address for deposit
}

⚠ If you have used VISAMASTER as provider, you must pass referer header (opens in a new tab) when you go to the invoice link (for example, pass referer header when you go to https://someaddress.com). Otherwise if there is no header (for example, you go to https://someaddress.com from Telegram message) you will be redirected to the WhiteBIT homepage

Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["Amount is too little for deposit"]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "provider": ["Cannot find currency for specified provider"]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "uniqueId": ["The unique id has already been taken."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["The amount must be a number."],
    "provider": ["The selected provider is invalid."],
    "ticker": ["The selected ticker is invalid."]
  }
}
{
  "code": 10,
  "message": "Failed to generate deposit url"
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["The amount field is required."],
    "provider": ["The provider field is required."],
    "ticker": ["The ticker field is required."],
    "uniqueId": ["The unique id field is required."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "successLink": [
      "Your domain is incorrect. Please contact support for more details"
    ],
    "failureLink": [
      "Your domain is incorrect. Please contact support for more details"
    ]
  }
}
{
  "success": false,
  "message": "You don't have permission to use this endpoint. Please contact support for more details",
  "code": 0
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "successLink": ["Uri domain must have only https scheme"],
    "failureLink": ["Uri domain must have only https scheme"]
  }
}

Create withdraw request

[POST] /api/v4/main-account/withdraw

This endpoint creates withdraw for the specified ticker.

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
tickerStringYesCurrencies ticker. Example: BTC ⚠ Currencies ticker must have "can_deposit" status equal to "true". Use this url (opens in a new tab) to know more about currency.
amountNumeric stringYesWithdraw amount (including fee). If you want fee to be added to the specified amount, you need to use /main-account/withdraw-pay request (see examples there)
addressStringYesTarget address (wallet address for cryptocurrencies, identifier/card number for fiat currencies)
memoStringYes, if currency is memoableTarget address (wallet address for cryptocurrencies, identifier/card number for fiat currencies)
uniqueIdStringYesUnique transaction identifier. ⚠ Note that you should generate new unique id for each withdrawal request.
providerStringYes, if currency is fiatFiat currency provider. Example: VISAMASTER ⚠ Currency provider should be taken from https://whitebit.com/api/v4/public/assets (opens in a new tab) response.
networkStringNoCryptocurrency network. Available for multi network currencies. Example: OMNI ⚠ Currency network should be taken from https://whitebit.com/api/v4/public/assets (opens in a new tab) response. Default for USDT is ERC20
partialEnableBooleanNoOptional parameter for FIAT withdrawals with increased Maximum Limit if set as “true”. In order to use this parameter your application should support “Partially successful” withdrawal status and latest updates in deposit/withdrawal history.
beneficiaryObjectYes, if currency ticker is one of: UAH_IBAN, USD_VISAMASTER, EUR_VISAMASTER, USD, EURBeneficiary information data array.
beneficiary.firstNameStringYes, if currency ticker is one of: UAH_IBAN, USD_VISAMASTER, USD, EURBeneficiary first name. Max length: 40 symbols, latin letters and special characters.
beneficiary.lastNameStringYes, if currency ticker is one of: UAH_IBAN, USD_VISAMASTER, USD, EURBeneficiary last name. Max length: 40 symbols, latin letters and special characters.
beneficiary.tinIntegerYes, if currency is UAH_IBANBeneficiary TAX payer number. Integer, 10 digits.
beneficiary.phoneStringYes, if currency ticker is one of: USD_VISAMASTER, EUR_VISAMASTERBeneficiary phone number.
beneficiary.emailStringYes, if currency ticker is one of: USD_VISAMASTER, EUR_VISAMASTERBeneficiary email.

Request BODY raw:

{
  "ticker": "ETH",
  "amount": "0.9",
  "address": "0x0964A6B8F794A4B8d61b62652dB27ddC9844FB4c",
  "uniqueId": "24529041",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Request BODY (for multinetwork currency) raw:

{
  "ticker": "USDT",
  "amount": "0.9",
  "address": "0x0964A6B8F794A4B8d61b62652dB27ddC9844FB4c",
  "uniqueId": "24529042",
  "network": "ERC20",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Request BODY (for fiat currency) raw:

{
  "ticker": "UAH",
  "amount": "100",
  "provider": "VISAMASTER",
  "uniqueId": "24529043",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Request BODY (for fiat currency with partialEnable) raw:

{
  "ticker": "UAH",
  "amount": "50000",
  "address": "4111111111111111",
  "provider": "VISAMASTER_PAYCORE",
  "partialEnable": true,
  "uniqueId": "24529045",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Request BODY (for fiat IBAN currency) raw:

{
  "ticker": "UAH",
  "amount": "50000",
  "address": "UA213223130000026007233566001",
  "beneficiary": {
    "firstName": "Firstname",
    "lastName": "Lastname",
    "tin": 1000000000
  },
  "provider": "UAH_IBAN",
  "uniqueId": "24529045",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Request BODY (for fiat USD_VISAMASTER, EUR_VISAMASTER payment providers) raw:

{
  "ticker": "USD",
  "amount": "30000",
  "address": "4111111111111111",
  "beneficiary": {
    "firstName": "Firstname",
    "lastName": "Lastname",
    "phone": "1234567891",
    "email": "john_doe@email.com"
  },
  "provider": "USD_VISAMASTER",
  "uniqueId": "24529045",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response: Available statuses:

  • Status 201 if validation succeeded and withdraw creation process is started
  • Status 400 if request validation failed
  • Status 422 if inner validation failed

Response error codes:

  • 1 - currency is not withdrawable
  • 2 - specified address is invalid
  • 3 - amount is too small
  • 4 - amount is too small for the payment system
  • 5 - not enough balance
  • 6 - amount is less than or equals fee
  • 7 - amount should be integer (can happen for currencies with zero precision like Neo)
  • 8 - target withdraw amount without fee equals zero
  • 9 - address is unavailable (occurs for withdraws to own address)
[
  // empty array - has success status - go to deposit/withdraw history and check you request status by uniqueId
]
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "address": ["The address field is required."],
    "amount": ["The amount field is required."],
    "ticker": ["The ticker field is required."],
    "uniqueId": ["The unique id field is required."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "uniqueId": ["The unique id has already been taken."]
  }
}

Errors for unconfirmed users (without KYC):

{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": [
      "This currency has no active pairs or it may have been delisted. Its rate cannot be calculated at the moment.",
      "Current limit exceeded"
    ]
  }
}

Also, fiat currencies can't be withdrawn without KYC:

{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["Your account must be verified"]
  }
}
{
  "code": 2,
  "message": "Inner validation failed",
  "errors": {
    "address": ["The address is invalid"]
  }
}
{
  "code": 5,
  "message": "Inner validation failed",
  "errors": {
    "amount": ["Not enough money, Ethereum balance = 1"]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "ticker": ["The selected ticker is invalid."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "provider": ["Provider is required for fiat currency"]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "memo": ["The memo field is required."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "partialEnable": ["The partial enable field must be true or false."]
  }
}
{
  "message": "Too Many Attempts.", // In case of throttling
  "code": 0
}

Create withdraw request with the specific withdraw amount (fee is not included)

[POST] /api/v4/main-account/withdraw-pay

This endpoint has the similar logic as /main-account/withdraw, but with the only difference: amount that is specified will not include fee (it will be calculated to make target withdraw amount equal to the specified amount).

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Example:

  • When you create base withdraw and set amount = 100 USD, receiver will recieve 100 USD - fee amount, and your balance will decrease by 100 USD.
  • When you use this endpoint and set amount = 100 USD, receiver will recieve 100 USD, and your balance will decrease by 100 USD + fee amount.

Transfer between balances

[POST] /api/v4/main-account/transfer

This endpoint transfers the specified amount between main, trade and collateral balances

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
methodStringNo if from and to are setMethod We highly recommend to use from and to fields, which provides more flexibility. This way will be deprecated in future. Example: deposit if you need to transfer from main to trade / withdraw if you need to transfer from trade balance to main. For collateral balances you can use collateral-deposit to transfer from main to collateral balance and collateral-withdraw to transfer from collateral balance to main
fromStringNo if method is setBalance FROM which funds will move to. Acceptable values: main, spot, collateral
toStringNo if method is setBalance TO which funds will move to. Acceptable values: main, spot, collateral
tickerStringYesCurrency's ticker. Example: BTC
amountNumeric stringYesAmount to transfer. Max precision = 8, value should be greater than zero and less or equal your available balance.

Request BODY raw:

{
  "ticker": "XLM",
  "amount": "0.9",
  "method": "deposit",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response: Available statuses:

  • Status 201 if all validations succeeded and creating transaction is started
  • Status 400 if request validation failed
  • Status 422 if inner validation failed

Response error codes:

  • 1 - transfers from trade to main are disabled
  • 2 - transfers from main to trade are disabled
  • 3 - not enough balance
[
  // empty array - has success status
]
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["The amount field is required."],
    "method": ["The method field is required."],
    "ticker": ["The ticker field is required."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "ticker": ["The selected ticker is invalid."]
  }
}

Errors for unconfirmed users (without KYC):

{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": [
      "This currency has no active pairs or it may have been delisted. Its rate cannot be calculated at the moment.",
      "Current limit exceeded"
    ]
  }
}

Also, fiat currencies can't be withdrawn without KYC:

{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["Your account must be verified"]
  }
}
{
  "code": 3,
  "message": "Inner validation failed",
  "errors": {
    "amount": [
      "You don't have such amount for transfer (available 34.68, in amount: 1000000)"
    ]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "method": ["The selected method is invalid."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["The amount must be at least 0.00000001."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["The amount must be a number.", "Invalid number"]
  }
}
{
  "message": "Too Many Attempts.", // In case of throttling
  "code": 0
}

Get deposit/withdraw history

[POST] /api/v4/main-account/history

This endpoint retrieves the history of deposits and withdraws

❗ Rate limit 200 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
transactionMethodNumberNoMethod. Example: 1 to display deposits / 2 to display withdraws. Do not send this parameter in order to receive both deposits and withdraws.
tickerStringNoCurrency's ticker. Example: BTC
addressStringNoCan be used for filtering transactions by specific address or memo.
addressesArrayNoCan be used for filtering transactions by specific addresses or memos (max: 20).
uniqueIdStringNoCan be used for filtering transactions by specific unique id
limitIntNoLIMIT is a special clause used to limit records a particular query can return. Default: 50, Min: 1, Max: 100
offsetIntNoIf you want the request to return entries starting from a particular line, you can use OFFSET clause to tell it where it should start. Default: 0, Min: 0, Max: 10000
statusArrayNoCan be used for filtering transactions by status codes. ❗ Caution: You must use this parameter with appropriate transactionMethod and use valid status codes for this method. You can find them below. Example: "status": [3,7]
Deposit status codes:
Successful - 3, 7
Canceled - 4, 9
Unconfirmed by user - 5
Frozen - 21
Uncredited - 22
Pending - 15
Withdraw status codes:
Pending - 1, 2, 6, 10, 11, 12, 13, 14, 15, 16, 17
Successful - 3, 7
Canceled - 4
Unconfirmed by user - 5
Frozen - 21
Partially successful - 18

Request BODY raw:

{
  "transactionMethod": "1",
  "ticker": "BTC",
  "offset": 0,
  "limit": 100,
  "status": [3, 7],
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response: Available statuses:

  • Status 201 if all validations succeeded and creating transaction is started
  • Status 400 if request validation failed
  • Status 422 if inner validation failed
{
    "limit": 100,
    "offset": 0,
    "records": [
        {
            "address": "3ApEASLcrQtZpg1TsssFgYF5V5YQJAKvuE",                                        // deposit address
            "uniqueId": null,                                                                       // unique Id of deposit
            "createdAt": 1593437922,                                                                // timestamp of deposit
            "currency": "Bitcoin",                                                                  // deposit currency
            "ticker": "BTC",                                                                        // deposit currency ticker
            "method": 1,                                                                            // called method 1 - deposit, 2 - withdraw
            "amount": "0.0006",                                                                     // amount of deposit
            "description": "",                                                                      // deposit description
            "memo": "",                                                                             // deposit memo
            "fee": "0",                                                                             // deposit fee
            "status": 15,                                                                           // transactions status
            "network": null,                                                                        // if currency is multinetwork
            "transactionHash": "a275a514013e4e0f927fd0d1bed215e7f6f2c4c6ce762836fe135ec22529d886",  // deposit transaction hash
            "transactionId": "5e112b38-9652-11ed-a1eb-0242ac120002",                                // transaction id
            "details": {
                "partial": {                                                                        // details about partially successful withdrawals
                    "requestAmount": "50000",                                                       // requested withdrawal amount
                    "processedAmount": "39000",                                                     // processed withdrawal amount
                    "processedFee": "273",                                                          // fee for processed withdrawal amount
                    "normalizeTransaction": ""                                                      // deposit id
                }
            },
            "confirmations": {                                                                      // if transaction status == 15 (Pending) you can see this object
                "actual": 1,                                                                        // current block confirmations
                "required": 2                                                                       // required block confirmation for successful deposit
            }
        },
        {...},
        {...},
        {...}
    ],
    "total": 300                                                                                    // total number of  transactions, use this for calculating ‘limit’ and ‘offset'
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "limit": ["The limit field is required."],
    "offset": ["The offset field is required."],
    "transactionMethod": ["The transaction method field is required."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "ticker": ["The selected ticker is invalid."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "transactionMethod": ["The selected transaction method is invalid."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "limit": ["The limit may not be greater than 100."],
    "offset": ["The offset may not be greater than 10000."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "limit": ["The limit must be at least 1."],
    "offset": ["The offset must be at least 0."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "limit": ["The limit must be an integer."],
    "offset": ["The offset must be an integer."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "status": ["The selected status is invalid."]
  }
}

Create new address for deposit

[POST] /api/v4/main-account/create-new-address

This endpoint creates a new address even when the last created address is not used. This endpoint is not available by default, you need to contact support@whitebit.com in order to get permissions to use this endpoint.

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
tickerStringYesCurrency's ticker. Example: BTC
networkStringNoCurrency's network if it is multinetwork currency. Example: OMNI or TRC20 or ERC20. For USDT default network is ERC20(ETH).
typeStringNoAddress type, available for specific currencies list (see address types table below)

Address types:

CurrencyTypesDefault
BTCp2sh-segwit, bech32bech32
LTCp2sh-segwit, bech32bech32

Request BODY raw:

{
  "ticker": "XLM",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Request BODY (for multinetwork currency) raw:

{
  "ticker": "USDT",
  "network": "ERC20",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Request BODY (for BTC with specific address type):

{
  "ticker": "BTC",
  "type": "bech32",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response: Available statuses:

  • Status 201 if all validations succeeded and creating transaction is started
  • Status 400 if request validation failed
  • Status 422 if inner validation failed
{
  "account": {
    "address": "GDTSOI56XNVAKJNJBLJGRNZIVOCIZJRBIDKTWSCYEYNFAZEMBLN75RMN", // deposit address
    "memo": "48565488244493"                                               // memo if currency requires memo
  },
  "required": {
    "maxAmount": "0", // max amount of deposit that can be accepted by exchange - if you deposit more than that number, it won't be accepted by exchange
    "minAmount": "1", // min amount of deposit that accepted by exchange - if you deposit less than that number, it won't be accepted by exchange
    "fixedFee": "0",  // fixed deposit fee
    "flexFee": {      // flexible fee - is fee that use percent rate
      "maxFee": "0",  // maximum fixed fee that you will pay
      "minFee": "0",  // minimum fixed fee that you will pay
      "percent": "0"  // percent of deposit that you will pay
    }
  }
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "ticker": ["The ticker field is required."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "ticker": ["The selected ticker is invalid."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "network": ["Unsupported network"]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "network": ["The network must be a string."],
    "ticker": ["The ticker must be a string."]
  }
}

Codes

Create code

[POST] /api/v4/main-account/codes

This endpoint creates WhiteBIT code.

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
tickerStringYesCurrency's ticker. Example: BTC
amountNumeric stringYesAmount to transfer. Max precision = 8, value should be greater than zero and your main balance.
passphraseStringNoPassphrase that will be used for applying codes. Passphrase must contain only latin letters, numbers and symbols (like !@#$%^, no whitespaces). Max: 25 symbols.
descriptionStringNoAdditional text description for code. Visible only for creator Max: 75 symbols.

Request BODY raw:

{
  "ticker": "ETH",
  "amount": "0.002",
  "passphrase": "some passphrase",
  "description": "some description",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response: Available statuses:

  • Status 201 if all validations succeeded and creating transaction is started
  • Status 400 if request validation failed
  • Status 422 if inner validation failed

Response error codes:

  • 0 - Fiat are available on the front-end only
  • 1 - currency is not withdrawable
  • 2 - specified address is invalid
  • 3 - amount is too small
  • 4 - amount is too small for the payment system
  • 5 - not enough balance
  • 6 - amount is less than or equals fee
{
  "code": "WBe11f4fce-2a53-4edc-b195-66b693bd77e3ETH", // generated WhiteBIT code
  "message": "Code was successfully created",
  "external_id": "be08a482-5faf-11ed-9b6a-0242ac120002"
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["The amount field is required."],
    "ticker": ["The ticker field is required."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["The amount must be a number.", "Invalid number"],
    "description": ["The description must be a string."],
    "passphrase": ["The passphrase must be a string."],
    "ticker": ["The selected ticker is invalid."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["The amount must be at least 0."],
    "description": ["The description may not be greater than 75 characters."],
    "passphrase": ["The passphrase may not be greater than 25 characters."],
    "ticker": ["The selected ticker is invalid."]
  }
}

Errors for unconfirmed users (without KYC):

{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": [
      "This currency has no active pairs or it may have been delisted. Its rate cannot be calculated at the moment.",
      "Current limit exceeded"
    ]
  }
}

Also, fiat currencies can't be withdrawn without KYC:

{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["Your account must be verified"]
  }
}

Passphrase must contain only latin letters, numbers and symbols (like !@#$%^, no whitespaces)

{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "passphrase": ["The passphrase format is invalid."]
  }
}

Apply code

[POST] /api/v4/main-account/codes/apply

This endpoint applies WhiteBIT code.

❗ Rate limit 60 requests/1 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
codeStringYesCode that will be applied.
passphraseStringNoShould be provided if the code was created with passphrase Max: 25 symbols.

Request BODY raw:

{
  "code": "WBe11f4fce-2a53-4edc-b195-66b693bd77e3ETH",
  "passphrase": "some passphrase",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response: Available statuses:

  • Status 201 if all validations succeeded and creating transaction is started
  • Status 400 if request validation failed
  • Status 422 if inner validation failed
{
  "message": "Code was successfully applied",
  "ticker": "ETH",
  "amount": "0.002",
  "external_id": "be08a482-5faf-11ed-9b6a-0242ac120002"
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "code": ["The code field is required."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "code": ["Incorrect code or passphrase"]
  }
}

Get my codes

[POST] /api/v4/main-account/codes/my

This endpoint retrieves the list of WhiteBIT codes created by my account.

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
limitIntNoLIMIT is a special clause used to limit records a particular query can return. Default: 30, Min: 1, Max: 100
offsetIntNoIf you want the request to return entries starting from a particular line, you can use OFFSET clause to tell it where it should start. Default: 0, Min: 0, Max: 10000

Request BODY raw:

{
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response: Available statuses:

  • Status 201 if all validations succeeded and creating transaction is started
  • Status 400 if request validation failed
  • Status 422 if inner validation failed
{
    "total": 15,
    "data": [
        {
            "amount": "0.002",                                    // code amount
            "code": "WBe11f4fce-2a53-4edc-b195-66b693bd77e3ETH",  // code
            "date": 1598296332,                                   // code creation timestamp
            "status": "Activated",                                // code status
            "ticker": "ETH",                                      // code ticker
            "external_id": "cf7c3ff8-5eb0-11ed-9b6a-0242ac120002" // code external id
        },
        {...}
    ],
    "limit": 30,
    "offset": 0
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "limit": ["The limit may not be greater than 100."],
    "offset": ["The offset may not be greater than 10000."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "limit": ["The limit must be at least 1."],
    "offset": ["The offset must be at least 0."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "limit": ["The limit must be an integer."],
    "offset": ["The offset must be an integer."]
  }
}

Get codes history

[POST] /api/v4/main-account/codes/history

This endpoint retrieves the whole codes history on your account.

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
limitIntNoLIMIT is a special clause used to limit records a particular query can return. Default: 30, Min: 1, Max: 100
offsetIntNoIf you want the request to return entries starting from a particular line, you can use OFFSET clause to tell it where it should start. Default: 0, Min: 0, Max: 10000

Request BODY raw:

{
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response: Available statuses:

  • Status 201 if all validations succeeded and creating transaction is started
  • Status 400 if request validation failed
  • Status 422 if inner validation failed
{
    "total": 29,
    "data": [
        {
            "amount": "+0.002",                                   // code amount change; - is created; + is applied
            "code": "WBe11f4fce-2a53-4edc-b195-66b693bd77e3ETH",  // code
            "date": 1598296734,                                   // code activation timestamp
            "status": "Activated",                                // current code status
            "ticker": "ETH",                                      // code ticker
            "external_id": "cf7c3ff8-5eb0-11ed-9b6a-0242ac120002" // code external id
        },
        {
            "amount": "-0.002",                                   // code amount change; - is created; + is applied
            "code": "WBe11f4fce-2a53-4edc-b195-66b693bd77e3ETH",  // code
            "date": 1598296332,                                   // code creation timestamp
            "status": "Activated",                                // current code status
            "ticker": "ETH",                                      // code ticker
            "external_id": "52995812-5eb1-11ed-9b6a-0242ac120002" // code external id
        },
        {...}
    ],
    "limit": 100,
    "offset": 0
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "limit": ["The limit may not be greater than 100."],
    "offset": ["The offset may not be greater than 10000."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "limit": ["The limit must be at least 1."],
    "offset": ["The offset must be at least 0."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "limit": ["The limit must be an integer."],
    "offset": ["The offset must be an integer."]
  }
}

Crypto Lеnding

This API provides endpoints for interacting with Crypto Lеnding: getting active plans, creating/closing investments, retrieving investments/interest payments history.

These endpoints are available only for B2B partner services, you need to fill the form https://whitebit.com/institutional-services/b2b (opens in a new tab) in order to get permissions to use these endpoints.

Get plans

[POST] /api/v4/main-account/smart/plans

This endpoint retrieves all active plans

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
tickerStringNoInvest plan source currency's ticker. Example: BTC

Request BODY raw:

{
  "ticker": "USDT",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response:

Available statuses:

  • Status 200
  • Status 400 if request validation failed
[
  {
    "id": "8e667b4a-0b71-4988-8af5-9474dbfaeb51", // Invest plan identifier
    "ticker": "USDT",                             // Source currency ticker
    "status": 1,                                  // Status (1 - active, 2 - no coins left, 3 - inactive, 4 - pause)
    "percent": "10",                              // Interest percent
    "duration": 14400,                            // Investment duration (in minutes)
    "interestTicker": "USDT",                     // Target currency ticker
    "interestRatio": "1",                         // Target currency to source currency ratio, see note
    "minInvestment": "100",                       // Min investment amount
    "maxInvestment": "10000",                     // Max investment amount
    "maxPossibleInvestment": "3000"               // Max investment amount due to current invest plan state
  }
]
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "ticker": ["The selected ticker is invalid."]
  }
}

Note: when target currency is different from source currency, interest amount in target currency will be calculated using interestRatio value.

Examples:

  • When source currency = USDT, target currency = BTC and interest ratio = 40000, it means that you will receive interest in BTC that equals interest amount in USDT divided by interest ratio (in this case 0.000025 BTC per each 1 USDT of interest amount).
  • When source currency equals target currency, interest ratio equals 1.

Invest

[POST] /api/v4/main-account/smart/investment

This endpoint creates a new investment to the specified invest plan

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
planIdStringYesInvest plan identifier
amountNumeric StringYesInvestment amount

Request BODY raw:

{
  "planId": "8e667b4a-0b71-4988-8af5-9474dbfaeb51",
  "amount": "100",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response:

Available statuses:

  • Status 201
  • Status 400 if request validation failed
  • Status 422 if inner validation failed
{
  "id": "0d7b66ff-1909-4938-ab7a-d16d9a64dcd5" // Investment identifier
}
Errors:

Request validation exceptions

{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "planId": ["The selected planId is invalid."],
    "amount": ["The amount must be a number.", "Invalid number"]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["The amount must be at least 0.000001."]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": [
      "The amount you are trying to invest is bigger than the amount left in this SMART plan. Please try investing a smaller amount."
    ]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "planId": ["Plan is disabled"]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "planId": ["Plan is inactive"]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "planId": ["There are no coins left in the plan"]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "planId": ["There are no coins left in the plan"]
  }
}
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "planId": ["Plan is paused"]
  }
}

Inner validation exceptions

When investment already exists, and you don't have permissions to create multiple investments by plan

{
  "code": 1,
  "message": "Inner validation failed",
  "errors": {
    "planId": ["The investment in this investment plan already exists"]
  }
}

When amount is less than min investment amount

{
  "code": 2,
  "message": "Inner validation failed",
  "errors": {
    "amount": [
      "The amount you're trying to invest is lower than the minimum amount in this investment plan."
    ]
  }
}

When amount is greater than max investment amount

{
  "code": 3,
  "message": "Inner validation failed",
  "errors": {
    "amount": [
      "The amount you're trying to invest exceeds the maximum amount in this investment plan."
    ]
  }
}

When there is not enough balance to create investment

{
  "code": 4,
  "message": "Inner validation failed",
  "errors": {
    "amount": [
      "Insufficient coins on your balance. 9 available, you're trying to invest 10"
    ]
  }
}

When there are no funds in plan to cover target interest amount

{
  "code": 5,
  "message": "Inner validation failed",
  "errors": {
    "amount": ["Insufficient funds for the payment."]
  }
}

Close investment

[POST] /api/v4/main-account/smart/investment/close

This endpoint closes active investment

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
idStringYesInvestment identifier

Request BODY raw:

{
  "id": "0d7b66ff-1909-4938-ab7a-d16d9a64dcd5",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response:

Available statuses:

  • Status 200
  • Status 400 if request validation failed
{}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "id": ["Investment not found"]
  }
}

Get investments history

[POST] /api/v4/main-account/smart/investments

This endpoint retrieves an investments history

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
idStringNoInvestment identifier
tickerStringNoInvest plan source currency's ticker
statusIntegerNoInvestment status (1 - active, 2 - closed)
limitIntNoLIMIT is a special clause used to limit records a particular query can return. Default: 100, Min: 1, Max: 100
offsetIntNoIf you want the request to return entries starting from a particular line, you can use OFFSET clause to tell it where it should start. Default: 0, Min: 0, Max: 10000

Request BODY raw:

{
  "id": "0d7b66ff-1909-4938-ab7a-d16d9a64dcd5",
  "ticker": "USDT",
  "status": 1,
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response:

Available statuses:

  • Status 200
  • Status 400 if request validation failed
{
  "offset": 0,
  "limit": 100,
  "records": [
    {
      "id": "0d7b66ff-1909-4938-ab7a-d16d9a64dcd5", // Investment id
      "plan": {                                     // Similar to the record from Get plans response
        "id": "8e667b4a-0b71-4988-8af5-9474dbfaeb51",
        "ticker": "USDT",
        "status": 1,
        "percent": "10",
        "duration": 14400,
        "interestTicker": "USDT",
        "interestRatio": "1",
        "minInvestment": "100",
        "maxInvestment": "10000",
        "maxPossibleInvestment": "3000"
      },
      "status": 1,               // Investment status (1 - active, 2 - closed)
      "created": 1646825196,     // Timestamp of investment creation
      "updated": 1646825196,     // Timestamp of investment update
      "paymentTime": 1646839596, // Timestamp of the payment time
      "amount": "100",           // Investment amount
      "interestPaid": "0"        // Interest paid amount
    }
  ]
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "id": ["The selected id is invalid."],
    "ticker": ["The selected ticker is invalid."],
    "status": ["The selected status is invalid."]
  }
}

Get interest payments history

[POST] /api/v4/main-account/smart/interest-payment-history

This endpoint retrieves the history of interest payments

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
planIdStringNoInvest plan identifier
tickerStringNoInvest plan target currency's ticker
limitIntNoLIMIT is a special clause used to limit records a particular query can return. Default: 100, Min: 1, Max: 100
offsetIntNoIf you want the request to return entries starting from a particular line, you can use OFFSET clause to tell it where it should start. Default: 0, Min: 0, Max: 10000

Request BODY raw:

{
  "planId": "8e667b4a-0b71-4988-8af5-9474dbfaeb51",
  "ticker": "USDT",
  "request": "{{request}}",
  "nonce": "{{nonce}}"
}

Response:

Available statuses:

  • Status 200
  • Status 400 if request validation failed
{
  "offset": 0,
  "limit": 100,
  "records": [
    {
      "planId": "8e667b4a-0b71-4988-8af5-9474dbfaeb51",       // Invest plan identifier
      "investmentId": "0d7b66ff-1909-4938-ab7a-d16d9a64dcd5", // Investment identifier
      "amount": "10",                                         // Interest amount
      "ticker": "USDT",                                       // Interest currency ticker
      "timestamp": 1646839596                                 // Transaction timestamp
    }
  ]
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "planId": ["The selected planId is invalid."],
    "ticker": ["The selected ticker is invalid."]
  }
}

Fees

This API provides an endpoint for getting deposit/withdrawal fees and limits by all currencies

Get fees

Returns an array of objects containing deposit/withdrawal settings for the corresponding currencies. Zero value in amount fields means that the setting is disabled.

[POST] /api/v4/main-account/fee

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Response:

Available statuses:

  • Status 200
[
  {
    "ticker": "BTC",         // Ticker
    "name": "Bitcoin",       // Currency name
    "can_deposit": "0",      // Status currency
    "can_withdraw": "0",     // Status currency
    "deposit": {             // Deposit fees/limits
      "minFlex": "0",        // Min fee amount when flex fee is enabled
      "maxFlex": "0",        // Max fee amount when flex fee is enabled
      "percentFlex": "0",    // Flex fee percent
      "fixed": "0",          // Fixed fee
      "minAmount": "0.0005", // Min deposit amount
      "maxAmount": "0"       // Max deposit amount
    },
    "withdraw": {            // Withdrawal fees/limits
      "minFlex": "0",        // Min fee amount when flex fee is enabled
      "maxFlex": "0",        // Max fee amount when flex fee is enabled
      "percentFlex": "0",    // Flex fee percent
      "fixed": "0.0004",     // Fixed fee
      "minAmount": "0.001",  // Min withdrawal amount
      "maxAmount": "0"       // Max withdrawal amount
    }
  }
]

Sub Account

This API provides endpoints to manage sub-accounts

Create Sub-Account

[POST] /api/v4/sub-account/create

This endpoint creates new sub-account

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
aliasStringYesName for sub-account
emailStringNoSub-account email. If this field is provided on this e-mail address will be sent invitation link. If not - new user without e-mail will be created
shareKycboolNoIf KYC shared with main account
permissionsobjectYesSub-account permissions
permissions.spotEnabledboolYesEnable spot trading
permissions.collateralEnabledboolYesEnable collateral trading

Request BODY raw:

{
  "alias": "training",
  "email": "email@google.com",
  "shareKyc": true,
  "permissions" : {
    "spotEnabled": true,
    "collateralEnabled": false
  }
}

Response:

Available statuses:

  • Status 201
  • Status 400 if request validation failed
{
  "id": "8e667b4a-0b71-4988-8af5-9474dbfaeb51",     // subaccount id
  "alias": "training",
  "userId": "0d7b66ff-1909-4938-ab7a-d16d9a64dcd5", // user accociated with account
  "email": "e***@g***m",
  "status": "active",
  "color": "#FF0000",
  "kyc" : {
    "shareKyc": true,
    "kycStatus": "shared"
  },
  "permissions": {
    "spotEnabled": true,
    "collateralEnabled": false,
  }
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "alias": ["Alias already exists."],
    "email": ["Email is invalid."],
  }
}

Delete Sub-Account

[POST] /api/v4/sub-account/delete

This endpoint deletes sub-account

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
idStringYesSub-account id

Request BODY raw:

{
  "id": "8e667b4a-0b71-4988-8af5-9474dbfaeb51"
}

Response:

Available statuses:

  • Status 200
  • Status 400 if request validation failed
{
  // empty response
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "id": ["Sub-account do not exists"],
  }
}

Edit Sub-Account

[POST] /api/v4/sub-account/edit

This endpoint edit sub-account

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
idstringyesSub-account id
aliasStringYesName for sub-account
permissionsobjectYesSub-account permissions
permissions.spotEnabledboolYesEnable spot trading
permissions.collateralEnabledboolYesEnable collateral trading

Request BODY raw:

{
  "id": true,
  "alias": "training",
  "permissions" : {
    "spotEnabled": true,
    "collateralEnabled": false
  }
}

Response:

Available statuses:

  • Status 200
  • Status 400 if request validation failed
{
//empty response
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "alias": ["Alias already exists."]
  }
}

List of Sub-Accounts

[POST] /api/v4/sub-account/list

This endpoint returns list of current user sub-accounts

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
searchStringNoSearch term
limitIntNoLIMIT is a special clause used to limit records a particular query can return. Default: 30, Min: 1, Max: 100
offsetIntNoIf you want the request to return entries starting from a particular line, you can use OFFSET clause to tell it where it should start. Default: 0, Min: 0, Max: 10000

Request BODY raw:

{
  "search": "training",
  "limit": 10,
  "offset": 0
}

Response:

Available statuses:

  • Status 200
  • Status 400 if request validation failed
{
  "offset": 0,
  "limit": 10,
  "data": [
    {
      "id": "8e667b4a-0b71-4988-8af5-9474dbfaeb51",     // subaccount id
      "alias": "training",
      "userId": "0d7b66ff-1909-4938-ab7a-d16d9a64dcd5", // user accociated with account
      "email": "e***@g***m",
      "status": "active",
      "color": "#FF0000",
      "kyc" : {
        "shareKyc": true,
        "kycStatus": "shared"
      },
      "permissions": {
        "spotEnabled": true,
        "collateralEnabled": false,
      }
    }
  ]
}

Sub-Account Transfer

[POST] /api/v4/sub-account/transfer

This endpoint creates transfer from main account to sub-account or vice versa

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
idStringYesSub-account id
directionStringYesTransfer direction. Values: "main_to_sub" or "sub_to_main".
amountNumeric StringYesTransfer amount. Min '0.00000001'
tickerStringYesCurrencies ticker.

Request BODY raw:

{
  "id": "8e667b4a-0b71-4988-8af5-9474dbfaeb51",
  "direction": "main_to_sub",
  "amount": "42.0",
  "ticker": "USDC"
}

Response:

Available statuses:

  • Status 200
  • Status 400 if request validation failed
{
  // empty response
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "amount": ["Amount is invalid"],
    "ticker": ["Ticker do not exists"],
    "id": ["Sub-account do not exists"],
  }
}

Block Sub-Account

[POST] /api/v4/sub-account/block

This endpoint blocks sub-account

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
idStringYesSub-account id

Request BODY raw:

{
  "id": "8e667b4a-0b71-4988-8af5-9474dbfaeb51",
}

Response:

Available statuses:

  • Status 200
  • Status 400 if request validation failed
{
  // empty response
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "id": ["Sub-account do not exists"],
    "account": ["Sub-account already blocked"],
  }
}

Unblock Sub-Account

[POST] /api/v4/sub-account/unblock

This endpoint unblocks sub-account

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
idStringYesSub-account id

Request BODY raw:

{
  "id": "8e667b4a-0b71-4988-8af5-9474dbfaeb51",
}

Response:

Available statuses:

  • Status 200
  • Status 400 if request validation failed
{
  // empty response
}
Errors:
{
  "code": 0,
  "message": "Validation failed",
  "errors": {
    "id": ["Sub-account do not exists"],
    "account": ["Sub-account already unblocked"],
  }
}

Sub-Account Balances

[POST] /api/v4/sub-account/balances

This endpoint returns sub-account balances

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
idStringYesSub-account id.
tickerStringNoCurrencies ticker. If not provided, returns data by all currencies

Request BODY raw:

{
  "id": "8e667b4a-0b71-4988-8af5-9474dbfaeb51",
  "ticker": "USDC"
}

Response:

Available statuses:

  • Status 200
  • Status 422 if request validation failed
{
  "USDC": [
    {
      "main": "42",
      "spot": "10",
      "collateral": "14"
    }
  ]
}
Errors:
{
  "code": 422,
  "message": "Account is not confirmed"
}

Get Sub-Account Transfer History

[POST] /api/v4/sub-account/transfer/history

This endpoint returns history of transfers between main account and sub-account

❗ Rate limit 1000 requests/10 sec.

Response is cached for: NONE

Parameters:

NameTypeMandatoryDescription
idStringNoSub-account id. If ot provided for all sub-accounts
directionStringNoTransfer direction. Values: "main_to_sub" or "sub_to_main". If provided, returns transactions in selected direction. If not provided, returns all transactions between main account and sub-account
limitIntNoLIMIT is a special clause used to limit records a particular query can return. Default: 30, Min: 1, Max: 100
offsetIntNoIf you want the request to return entries starting from a particular line, you can use OFFSET clause to tell it where it should start. Default: 0, Min: 0, Max: 10000

Request BODY raw:

{
  "id": "8e667b4a-0b71-4988-8af5-9474dbfaeb51",
  "direction": "main_to_sub"
}

Response:

Available statuses:

  • Status 200
  • Status 422 if request validation failed
{
  "offset": 0,
  "limit": 30,
  "data": [
    {
      "id": "0d7b66ff-1909-4938-ab7a-d16d9a64dcd5", // transaction id
      "direction": "main_to_sub",
      "currency": "USDT",
      "amount": "3.14",
      "createdAt": 1715339355
    }
  ]
}
Errors:
{
  "code": 422,
  "message": "Account is not confirmed"
}