SOFA_MOCK_SERVER

command module
v0.0.0-...-7030ca0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 1, 2023 License: Apache-2.0 Imports: 5 Imported by: 0

README

Table of contents

Get Started

How to deposit?

  • Setup a deposit wallet and configure it (via web control panel)
    • Refer to CYBAVO VAULT SOFA User Manual for detailed steps.
  • Request an API code/secret (via web control panel)
  • Create deposit addresses (via CYBAVO SOFA API)
  • Waiting for the CYBAVO SOFA system detecting transactions to those deposit addresses
  • Handle the deposit callback
    • Use the callback data to update certain data on your system.
    • Security Enhancement: Use the Query Callback Detail API to confirm the callback is sent from the CYBAVO SOFA system.
    • Refer to Callback Integration for detailed information.

How to withdraw?

  • Setup a withdrawal wallet and configure it (via web control panel)
    • Refer to CYBAVO VAULT SOFA User Manual for detailed steps.
  • Request an API code/secret (via web control panel)
  • Make withdraw request (via CYBAVI SOFA API)
    • Refer to Withdraw Assets API
    • Security Enhancement: Also set the withdrawal authentication callback URL to authorize the withdrawal requests sent to the CYBAVO SOFA system.
  • Waiting for the CYBAVO SOFA system broadcasting transactions to blockchain
  • Handle the withdrawal callback
    • Use the callback data to update certain data on your system.
    • Refer to Callback Integration for detailed information.

Try it now

Start integration

API Authentication

  • The CYBAVO SOFA system verifies all incoming requests. All requests must include X-API-CODE, X-CHECKSUM headers otherwise caller will get a 403 Forbidden error.

How to acquire and refresh API code and secret

  • Request the API code/secret from the Wallet Details page on the web control panel for the first time.
  • A paired refresh code can be used in the refresh API to acquire the new inactive API code/secret of the wallet.
    • Before the inactive API code is activated, the currently activated API code is still valid.
    • Once the paired API code becomes invalid, the paired refresh code will also become invalid.

How to make a correct request?

  • Put the API code in the X-API-CODE header.
    • Use the inactivated API code in any request will activate it automatically. Once activated, the currently activated API code will immediately become invalid.
    • Or you can explicitly call the activation API to activate the API code before use
  • Calculate the checksum with the corresponding API secret and put the checksum in the X-CHECKSUM header.
    • The checksum calculation will use all the query parameters, the current timestamp, user-defined random string and the post body (if any).
  • Please refer to the code snippet on the github project to know how to calculate the checksum.

Read-only API Code

  • A read-only API code can be used to call all the read functions of wallets.
    • All the read functions will be labeled VIEW in front of the API definition.
  • Use activation API with the WALLET_ID set as readonly to activate a read-only API code.
    • The full API path is /v1/sofa/wallets/readonly/apisecret/activate
    • After activation, the API code will remain valid until it is replaced by a newly activated read-only API code.
  • Use listing API to list all wallets that can be accessed through a read-only API code.

Callback Integration

  • Please note that the wallet must have an activated API code, otherwise no callback will be sent.
  • How to distinguish between deposit and withdrawal callbacks?
    • Deposit Callback (callback type 1)
      • The combination of txid and vout_index of the callback is unique, use this combined ID to identify the deposit request, not to use only the transaction ID (txid field). Because multiple deposit callbacks may have the same transaction ID, for example, BTC many-to-many transactions.
    • Withdrawal Callback (callback type 2)
      • The order_id of the callback is unique, use this ID to identify the withdrawal request.
It is important to distinguish between unique callbacks to avoid improper handling of deposit / withdrawal requests.

  • To ensure that the callbacks have processed by callback handler, the CYBAVO SOFA system will continue to send the callbacks to the callback URL until a callback confirmation (HTTP/1.1 200 OK) is received or exceeds the number of retries (retry time interval: 1-3-5-15-45 mins).

    • If all attempts fail, the callback will be set to a failed state, the callback handler can call the resend deposit callback or resend withdrawal callback API to request CYBAVO SOFA system to resend such kind of callback(s) or through the web control panel.

  • Refer to Callback Definition, Callback Type Definition for detailed definition.

  • Please refer to the code snippet on the github project to know how to validate the callback payload.

  • Best practice:

    • While processing a deposit callback, in addition to verifying the checksum of the callback, use Query Callback Detail API with the serial ID of the callback to perform an additional confirmation.

Callback State Change

The state of a successful withdrawal request is changed as follows:

processing state(1) -> transaction in pool state(2) -> transaction in chain state(3) -> repeats state 3 until the confirmation count is met

The state of a successful deposit request is changed as follows:

transaction in chain state(3) -> repeats state 3 until the confirmation count is met

Refer to Transaction State Definition for all transaction states definition.

In-pool Transaction Callback

Currently, only BTC supports in-pool transaction callbacks. The callback type is In-pool Transaction Callback(127), which is a one-time callback.

The following is an in-pool transaction callback example:

{
  "type": 127,
  "serial": 0,
  "order_id": "",
  "currency": "BTC",
  "txid": "675959d855da3a194d7f9d32b347ec2702d29677f23c563bc2c31aefaa274739",
  "block_height": 0,
  "tindex": 0,
  "vout_index": 0,
  "amount": "1000",
  "fees": "",
  "memo": "",
  "broadcast_at": 0,
  "chain_at": 0,
  "from_address": "",
  "to_address": "2Mw6znX6LgyFRhE9iM2d1TXBTP7MQiKD36y",
  "wallet_id": 367628,
  "state": 2,
  "confirm_blocks": 0,
  "processing_state": 0,
  "addon": {
    "fee_decimal": 8,
    "token_id": ""
  },
  "decimal": 8,
  "currency_bip44": 0,
  "token_address": ""
}

The processing_state always be 0 (In fullnode mempool) and state always be 2 (TXID in pool).

Cryptocurrency Unit Conversion

For callback
  • The amount and fees fields in the callback are in the smallest cryptocurrency unit, use decimal and fee_decimal(in the addon field) fields of callback data to convert the unit.
For API
  • Refer to decimals of Currency Definition to convert main cryptocurrency unit.
  • For the cryptocurrency token, use the token_decimals field of the Wallet Info API to convert cryptocurrency token unit.

API Response Validation

  • A succuessful API response (status code 200) will contain an X-CHECKSUM header for integrity and security checks.

    • Calculate the checksum with the corresponding wallet's API secret to double confirm the integrity of the response and the validity of the source.

  • Please refer to the code snippet on the github project to know how to validate the API response.

REST API

Deposit Wallet API

Create Deposit Addresses

Create deposit addresses on certain wallet. Once addresses are created, the CYBAVO SOFA system will callback when transactions are detected on these addresses.

TIP: Use the Verification API to verify the address before depositing assets.

Request

POST /v1/sofa/wallets/WALLET_ID/addresses

Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/107950/addresses
Post body

For BNB, XLM, XRP or EOS wallet:

{
  "count": 2,
  "memos": ["10001", "10002"],
  "labels": ["note-for-001", "note-for-002"]
}

For wallet excepts BNB, XLM, XRP and EOS:

{
  "count": 2,
  "labels": ["note-for-address-1", "note-for-address-2"]
}

The request includes the following parameters:

Post body
Field Type Note Description
count int required, max 1000 Specify address count
memos array required (creating BNB, XLM, XRP or EOS wallet) Specify memos for BNB, XLM, XRP or EOS deposit wallet. Refer to Memo Requirement
labels array optional Specify the labels of the generated addresses or memos

NOTE: The length of memos must equal to count while creating addresses for BNB, XLM, XRP or EOS wallet.

NOTE: The memos(or called destination tags) of XRP must be strings that can be converted to numbers.

If use the labels to assign labels, the array length of the labels must equal to count. The label will be automatically synced to the child wallet.

Response Format

An example of a successful response:

For BNB, XLM, XRP or EOS wallet:

{
  "addresses": ["10001", "10002"]
}

For wallet excepts BNB, XLM, XRP or EOS:

{
  "addresses": [
    "0x2E7248BBCD61Ad7C33EA183A85B1856bc02C40b6",
    "0x4EB990D527c96c64eC5Bfb0D1e304840052d4975",
    "0x86434604FF857702fbE11cBFf5aC7689Af19c4Ed"
  ]
}

For the ETH wallet that uses contract collection:

{
  "txids": [
    "0xe6dfe0d283690f636df5ea4b9df25552e6b576b88887bfb5837016cdd696e754",
    "0xdb18fd33c9a6809bfc341a1c0b2c092be5a360f394c85367f9cf316579281ab4",
    "0x18075ff1693026f93722f8b2cc0e29bf148ded5bce4dc173c8118951eceabe60",
    "0x7c6acb506ef033c09f781cc5ad6b2d0a216346758d7f955e720d6bc7a52731a5",
    "0x7da19f8c0d82cde16636da3307a6bef46eb9f398af3eb2362d230ce300509d63"
  ]
}

For the delegated wallet:

  "address_indexes": [
    1,
    2,
    3,
    4,
    5
  ],
  "addresses": [
    "0xB02B189b423f58E1c035f02786eA5BC6E7762718",
    "0xace596bfd34E86d15F28b1743B99B26FAFcCC9F5",
    "0x22505d4E113aE8b7A7ACdAECABfD9601E0c41ca8",
    "0x219028837aB831077D2F12EC134cE3C59266EDfd",
    "0x4C2216980B2883234C0C71ef272a195344f206BE"
  ]

Use Query Deployed Contract Deposit Addresses API to query deployed contract addresses.

The response includes the following parameters:

Field Type Description
addresses array Array of just created deposit addresses
txids array Array of transaction IDs used to deploy collection contract
address_indexes array Array of address index*

* The address indexes are mapping to the array of address. For example, the index of 0xB02B189b423f58E1c035f02786eA5BC6E7762718 is 1, and so on.

The index and address must be specified when calling Withdraw Assets API on the delegated wallet.

Use the Query Deposit Addresses API to retrieve the index of the delegated address.

Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 112 Invalid parameter - The count and the count of memos mismatched
403 385 API Secret not valid - Invalid API code permission
403 706 Exceed max allow wallet limitation, Upgrade your SKU to get more wallets - Reached the limit of the total number of deposit addresses
400 421 Mapped(Token) wallet not allow to create deposit addresses, please create the deposit wallet in parent wallet, the address will be synced to mapped wallet automatically - Only the parent wallet can create deposit addresses
400 500 insufficient fund - Insufficient balance to deploy collection contract
400 703 Operation failed Error message returned by JSON parser Malformatted post body
400 818 Destination Tag must be integer - Wrong XRP destination tag format
400 945 The max length of BNB memo is 256 chars - Reached the limit of the length of BNB memo
400 946 The max length of EOS memo is 128 chars - Reached the limit of the length of EOS memo
400 947 The max length of XRP destination tag is 20 chars - Reached the limit of the length of XRP destination tag
400 948 The max length of XLM memo is 20 chars - Reached the limit of the length of XLM memo
404 304 Wallet ID invalid archived wallet or wrong wallet type The wallet is not allowed to perform this request
Back to top

Verify Deposit Addresses

Verify that these addresses belong to a deposit wallet.

Request

VIEW POST /v1/sofa/wallets/WALLET_ID/receiver/addresses/verify

Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/98675/receiver/addresses/verify
Post body
{
  "addresses": [
    "0x46d4AD967F68253f61D45a044dC7dC7B13E5A4B3",
    "0x107FF19Ea5fB7de78392e7AcC2A2C7eace891bDc"
  ]
}

The request includes the following parameters:

Post body
Field Type Note Description
addresses array required Specify the addresses to be verified

If the address can not be found or invalid, it will not be listed in the response.

Response Format

An example of a successful response:

{
  "addresses": {
    "0x107FF19Ea5fB7de78392e7AcC2A2C7eace891bDc": {
      "create_time": "2021-12-05T16:23:20Z",
      "label": "987444413"
    },
    "0x46d4AD967F68253f61D45a044dC7dC7B13E5A4B3": {
      "create_time": "2021-12-05T16:23:20Z",
      "label": ""
    }
  }
}

The response includes the following parameters:

Field Type Description
addresses key-value pairs The address-info pairs
label string Associated label
create_time string Address creation time (UTC)
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Query Deposit Addresses

Query the deposit addresses created by the Create Deposit Addresses API.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/addresses?start_index=from&request_number=count

Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/179654/addresses?start_index=0&request_number=3

The request includes the following parameters:

Field Type Note Description
start_index int optional, default 0 Specify address start index
request_number int optional, default 1000, max 5000 Request address count
Response Format

An example of a successful response:

{
  "wallet_id": 179654,
  "wallet_count": 6,
  "wallet_address": [
    {
      "currency": 60,
      "token_address": "",
      "address": "0x8c42fD03A5cfba7C3Cd97AB8a09e1a3137Ef33C3",
      "memo": ""
    },
    {
      "currency": 60,
      "token_address": "",
      "address": "0x4d3EB54b602BF4985CE457089F9fB084Af597A2C",
      "memo": ""
    },
    {
      "currency": 60,
      "token_address": "",
      "address": "0x74dc3fB523295C87C0b93E48744Ce94fe3a8Ef5e",
      "memo": ""
    }
  ]
}

An example of a successful response of the delegated wallet:

{
  "wallet_id": 132342,
  "wallet_count": 7,
  "wallet_address": [
    {
      "address": "0xB02B189b423f58E1c035f02786eA5BC6E7762718",
      "address_index": 1,
      "currency": 99999999997,
      "memo": "",
      "token_address": ""
    },
    {
      "address": "0xace596bfd34E86d15F28b1743B99B26FAFcCC9F5",
      "address_index": 2,
      "currency": 99999999997,
      "memo": "",
      "token_address": ""
    },
    {
      "address": "0x22505d4E113aE8b7A7ACdAECABfD9601E0c41ca8",
      "address_index": 3,
      "currency": 99999999997,
      "memo": "",
      "token_address": ""
    }
  ]
}

The response includes the following parameters:

Field Type Description
wallet_id int64 ID of request wallet
wallet_address array Array of wallet addresses
wallet_count int64 Total count of deposit addresses
address_index int64 The corresponding index of the address

Refer to Currency Definition or here for more detailed currency definitions

If this is an ETH contract collection deposit wallet, only the deployed address will be returned.

Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Query Deployed Contract Deposit Addresses

Query deployed contract deposit addresses created by the Create Deposit Addresses API.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/addresses/contract_txid?txids=txid1,txid2

For the ETH contract collection deposit walle. Only deployed addresses will be returned.

Request Format

An example of the request:

API
/v1/sofa/wallets/179654/addresses/contract_txid?txids=0xe6dfe0d283690f636df5ea4b9df25552e6b576b88887bfb5837016cdd696e754,0xdb18fd33c9a6809bfc341a1c0b2c092be5a360f394c85367f9cf316579281ab4

The request includes the following parameters:

Field Type Note Description
txids string requried, max 10 transaction IDs Transaction ID used to deploy collection contract
Response Format

An example of a successful response:

{
  "addresses": {
    "0xdb18fd33c9a6809bfc341a1c0b2c092be5a360f394c85367f9cf316579281ab4": {
      "address": "0x00926cE2BbF56317c72234a0Fb8A65A1A15F7103",
      "currency": 60,
      "memo": "",
      "token_address": ""
    },
    "0xe6dfe0d283690f636df5ea4b9df25552e6b576b88887bfb5837016cdd696e754": {
      "address": "0xf3747e3edbd8B8414718dd51330415c171e79208",
      "currency": 60,
      "memo": "",
      "token_address": ""
    }
  }
}

The response includes the following parameters:

Field Type Description
addresses map object The map KEY is Transaction ID used to deploy collection contract and the map VALUE is the address information
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Query Pool Address

Get the pool address of a deposit wallet. The pool address has different functionality in different cryptocurrencies.

In BTC or ETH, the cryptocurrency in the pool address will be used to pay for token transfer(ex. USDT-Omni, ERC20).

BCH/BSV need at least 0.01 BCH/BSV in the pool address for polluting the non-fork coin and make the collection successfully.

In EOS, XRP, XLM or BNB, the pool address is the user's deposit address. All user deposits will be distinguished by memo / tag field.

LTC, DOGE, DASH, DOT(WND), FIL. SOL and ADA does not support pool address.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/pooladdress

Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/179654/pooladdress
Response Format

An example of a successful response:

{
  "address": "0x36099775afa8d6363aC8e5d0fC698306C021a858"
}

The response includes the following parameters:

Field Type Description
address string Pool address of wallet
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 703 this wallet does not support pool address - -
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Query Pool Address Balance

Get the pool address balance of a deposit wallet.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/pooladdress/balance

Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/179654/pooladdress/balance
Response Format

An example of a successful response:

{
  "balance": "0.515",
  "currency": 60,
  "unconfirm_balance": "0",
  "wallet_address": "0xb6ad80c96D093EA584AfcB9443927812d3e4Bd94"
}

The response includes the following parameters:

Field Type Description
balance string Pool address balance
unconfirm_balance string Unconfirmed pool address balance
currency int64 Cryptocurrency of the wallet
wallet_address string Pool address of the wallet
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Query Invalid Deposit Addresses

When an abnormal deposit is detected, the CYBAVO SOFA system will set the deposit address to invalid. Use this API to obtain the all invalid deposit addresses for further usage.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/addresses/invalid-deposit

Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/179654/addresses/invalid-deposit
Response Format

An example of a successful response:

{
  "addresses": ["0x5dB3d8C70dAa9C919F9962221c2fDDbe8EBAa5F2"]
}

The response includes the following parameters:

Field Type Description
addresses array Array of invalid deposit address
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Query Deposit Callback Detail

Query the detailed information of the deposit callback by the tx ID and the vout index.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/receiver/notifications/txid/TX_ID/VOUT_INDEX

Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/179654/receiver/notifications/txid/0xb72a81976f780445decd13a35c24974c4e32665cb57d79b3f7a601c775f6a7d8/0
Response Format

An example of a successful response:

{
  "notification": {
    "addon": {},
    "amount": "2000000000000000000",
    "block_height": 7757485,
    "broadcast_at": 1587441501,
    "chain_at": 1587441501,
    "confirm_blocks": 166027,
    "currency": "ETH",
    "fees": "126000000000000",
    "from_address": "0x8382Cc1B05649AfBe179e341179fa869C2A9862b",
    "memo": "",
    "order_id": "",
    "processing_state": 2,
    "serial": 90000000547,
    "state": 3,
    "tindex": 27,
    "to_address": "0x32d638773cB85965422b3B98e9312Fc9392307BC",
    "txid": "0xb72a81976f780445decd13a35c24974c4e32665cb57d79b3f7a601c775f6a7d8",
    "type": 1,
    "vout_index": 0,
    "wallet_id": 179654
  }
}

The response includes the following parameters:

Field Type Description
notification object Refer to Callback Definition
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The wallet is not allowed to perform this request or the callback (txid+vout_index) not found
Back to top

Resend Deposit/Collection Callbacks

The callback handler can call this API to resend pending, risk-controlled or failed deposit/collection callbacks.

Refer to Callback Integration for callback rules.

The resend operation could be requested on the web control panel as well.

Request

POST /v1/sofa/wallets/WALLET_ID/collection/notifications/manual

Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/179654/collection/notifications/manual
Post body
{
  "notification_id": 0
}

The request includes the following parameters:

Post body
Field Type Note Description
notification_id int64 required, 0 means all Specify callback ID to resend

This ID equal to the serial field of callback data.

Response Format

An example of a successful response:

{
  "count": 0
}

The response includes the following parameters:

Field Type Description
count int Count of callbacks just resent
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Query Deposit Wallet Balance

Get the deposit wallet balance.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/receiver/balance

Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/959272/receiver/balance
Response Format

An example of a successful response:

{
  "currency": 60,
  "token_address": "",
  "balance": "0.619673333517576",
  "token_balance": ""
}

The response includes the following parameters:

Field Type Description
currency int64 Registered coin types. Refer to Currency Definition
token_address string Token contract address
balance string Deposit wallet balance
token_balance string Deposit wallet token balance
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Update Deposit Address Label

Update the label of the deposit address.

Request

POST /v1/sofa/wallets/WALLET_ID/addresses/label

Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

The label will be automatically synced between the parent and child wallet.

Request Format

An example of the request:

API
/v1/sofa/wallets/98675/addresses/label
Post body
{
  "address": "0x2B974a3De0b491bB26e0bF146E6cDaC36EFD574a",
  "label": "take-some-notes"
}

The request includes the following parameters:

Post body
Field Type Note Description
address string required Specify address to update the label
label string optional, set empty to clear the label Specify the label of the address
Response Format

Status code 200 represnts a successful operation

Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
404 112 Invalid parameter - The address can not be found
Back to top

Query Deposit Address Label

Query the labels of the deposit addresses.

Request

VIEW POST /v1/sofa/wallets/WALLET_ID/addresses/get_labels

Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/98675/addresses/get_labels
Post body
{
  "addresses": [
    "0x2B974a3De0b491bB26e0bF146E6cDaC36EFD574a",
    "0xF401AC94D9672e79c68e56A6f822b666E5A7d644"
  ]
}

The request includes the following parameters:

Post body
Field Type Note Description
addresses array required Specify the addresses to query labels
Response Format

An example of a successful response:

{
  "labels": {
    "0x2B974a3De0b491bB26e0bF146E6cDaC36EFD574a": "take-some-notes",
    "0xF401AC94D9672e79c68e56A6f822b666E5A7d644": ""
  }
}

The response includes the following parameters:

Field Type Description
labels key-value pairs The address-label pairs

If the address can not be found, it will not be listed in the response.

Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Query Delegated Address Balance

Query the balace of delegated addresses.

Request

VIEW POST /v1/sofa/wallets/WALLET_ID/receiver/get-balances

Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/708453/receiver/get-balances
Post body
{
  "addresses": [
    "0x6A2969E4496d5b27967a68b411D7e0218943c1B6",
    "0x1EA22Ed0347E6C9f852cfcBEFE752A026450164b",
    "0x2baB9B3af6041960322a248d5315850fc79a3881"
  ]
}

The request includes the following parameters:

Post body
Field Type Note Description
addresses array required Specify the addresses to query balance

Maximum 10 addresses per inquiry, more than 10 addresses will be discarded automatically. If the address can not be found, it will not be listed in the response.

Response Format

An example of a successful response:

{
  "balances": {
    "0x1EA22Ed0347E6C9f852cfcBEFE752A026450164b": {
      "balance": "0.009979649723530324",
      "token_balance": "1",
      "token_id_balances": [
        {
          "token_id": "9901"
        }
      ]
    },
    "0x2baB9B3af6041960322a248d5315850fc79a3881": {
      "balance": "0",
      "token_balance": "0"
    },
    "0x6A2969E4496d5b27967a68b411D7e0218943c1B6": {
      "balance": "0.019979076967554852",
      "token_balance": "2",
      "token_id_balances": [
        {
          "token_id": "9903"
        },
        {
          "token_id": "9902"
        }
      ]
    }
  }
}

The response includes the following parameters:

Field Type Description
balances key-value pairs Listed addresses' balance
balance string Address balance. For token wallet this is the mapped wallet's balance.
token_balance string Wallet token balance
token_id_balances array For ERC1155, ERC721 token wallet
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Withdrawal Wallet API

Withdraw Assets

To withdraw assets from an withdrawal wallet, the caller must to provide an unique order_id for each request, the CYBAVO SOFA system will send the callback with the unique order_id when the withdrawal is success (from in pool state to in chain state).

By default, the withdraw API will perform the address check to verify that the outgoing address is good or not. If the address in the request is marked as a problematic address, the request will be aborted. The error message will identify the problematic addresses. Set the ignore_black_list to true to skip the address check.

The withdrawal API can also interact with the contracts (ERC/BEP 721/1155) deployed in the SOFA system.

⚠️ Alert: Use the query API to confirm the current withdrawal status when uncertain (e.g. request timeout) to prevent fund loss due to repetitive transaction.

Request

POST /v1/sofa/wallets/WALLET_ID/sender/transactions

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

The order_id must be prefixed. Find prefix from corresponding wallet detail on web control panel.

If withdraw BNB or XRP, this API will check whether the destination addresse needs memo / destination tag or not. If the address does need memo / destination tag, the API will fail without memo / destination tag specified.

Request Format

An example of the request:

The prefix is 888888_ in following sample request.

API
/v1/sofa/wallets/68451/sender/transactions
Post body
{
  "requests": [
    {
      "order_id": "888888_1",
      "address": "0x83eE561B2aBD000FF00d6ca22f38b29d4a760d4D",
      "amount": "0.0001",
      "memo": "memo-001",
      "user_id": "USER01",
      "message": "message-001",
      "block_average_fee": 5
    },
    {
      "order_id": "888888_2",
      "address": "0xf16B7B8900F0d2f682e0FFe207a553F52B6C7015",
      "amount": "0.0002",
      "manual_fee": 50
    },
    {
      "order_id": "888888_3",
      "address": "0x9638fa816ccd35389a9a98a997ee08b5321f3eb9",
      "amount": "0.0002",
      "message": "message-003"
    },
    {
      "order_id": "888888_4",
      "address": "0x2386b18e76184367b844a402332703dd2eec2a90",
      "amount": "0",
      "contract_abi": "create:0x000000000000000000000000000000000000000000000000000000000000138800000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000",
      "user_id": "USER04",
      "ignore_gas_estimate_fail": true
    },
    {
      "order_id": "888888_5",
      "address": "0x6A2969E4496d5b27967a68b411D7e0218943c1B6",
      "amount": "1",
      "token_id": "985552421"
    }
  ],
  "ignore_black_list": false
}

For delegated wallet

{
  "requests": [
    {
      "order_id": "132342_1001",
      "address": "0x480A8507C63A27f05cd29BfB3Bb4F7bA1B6ba102",
      "from_address": "0xEb0e93980Cd0C5D3868B7da32A5604085f9F813C",
      "from_address_index": 7,
      "amount": "0.1"
    },
    {
      "order_id": "132342_1002",
      "address": "0xfe67e5b57ecccaa3f95bb90466651391024f25fc",
      "amount": "0",
      "contract_abi": "transferFrom:0x0000000000000000000000006a2969e4496d5b27967a68b411d7e0218943c1b60000000000000000000000001ea22ed0347e6c9f852cfcbefe752a026450164b00000000000000000000000000000000000000000000000000000000000026ac",
      "from_address": "0x1EA22Ed0347E6C9f852cfcBEFE752A026450164b",
      "from_address_index": 20
    }
  ]
}

The request includes the following parameters:

Post body
Field Type Note Description
order_id string required, max 255 chars Specify an unique ID, order ID must be prefixed
address string required Outgoing address (address must be a contract address, if the contract_abi is not empty)
amount string required Withdrawal amount
contract_abi string required, if calls contract ABI Specify the ABI method and the parameters, in the format ABI_method:parameters
memo string optional Memo on blockchain (This memo will be sent to blockchain). Refer to Memo Requirement
user_id string optional Specify certain user
message string optional Message (This message only saved on CYBAVO, not sent to blockchain)
block_average_fee int optional, range 1~100 Use average blockchain fee within latest N blocks. This option does not work for XRP, XLM, BNB, DOGE, EOS, TRX, ADA, DOT and SOL cryptocurrencies.
manual_fee int optional, range 1~2000 Specify blockchain fee in smallest unit of wallet currency (For ETH/BSC/HECO/OKT/OP/ARB/CELO/FTM/PALM, the unit is gwei. The unit returned by the Query Average Fee API is wei, divided by 1000000000 to get the correct unit.. This option does not work for XRP, XLM, BNB, DOGE, EOS, TRX, ADA, DOT and SOL cryptocurrencies.
token_id string optional Specify the token ID to be transferred
from_address string required, for delegated wallet Specify the delegated address for the request
from_address_index int64 required, for delegated wallet Specify the corresponding index of the from_address
ignore_gas_estimate_fail boolean optional, default false FOR DEBUG PURPOSE ONLY. After setting, the ABI EVM gas estimation will not be performed(Apply to individual order).
ignore_black_list boolean optional, default false After setting, the address check will not be performed. Apply to all orders.

The order_id must be prefixed. Find prefix from corresponding wallet detail on web control panel

block_average_fee and manual_fee are mutually exclusive configurations. If neither of these fields is set, the fee will refer to corresponding withdrawal policy of the withdrawal wallet.

The format of the contract_abi is ABI_method:hex_parameters, for example: create:0x000000000000000000000000000000000000000000000000000000000000138800000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000. The parameters must be encoded by web3.eth.abi.encodeParameters() of web3.js.

Only mapped wallets can use contract_abi to call ABI on smart contracts.

Only ERC721/1155 token wallet can use token_id to transfer token. For ERC721 wallets, if token_id is specified, the amount will be treated as 1.

The block_average_fee and manual_fee do not work for XRP, XLM, BNB, DOGE, EOS, TRX, ADA, DOT and SOL cryptocurrencies.

Response Format

An example of a successful response:

{
  "results": {
    "1": 20000000001,
    "2": 20000000002
  }
}

The response includes the following parameters:

Field Type Description
results array Array of withdraw result (order ID/withdraw transaction ID pair), if succeeds

An example response of the request contains problematic addresses:

{
  "error_code": 827,
  "error": "Outgoing address in black list, abort transaction",
  "blacklist": {
    "0x83eE561B2aBD000FF00d6ca22f38b29d4a760d4D": [
      "Involve phishing activity",
      "Involve cybercrime related"
    ]
  }
}

The response includes the following parameters:

Field Type Description
error_code int The error code
error string The error message
blacklist object The object describes all problematic addresses and their causes.
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
403 827 Outgoing address in black list, abort transaction - Some outgoing addresses are blacklisted, examine the response 'blacklist' field for detailed information
400 112 Invalid parameter - Malformatted post body
400 112 Invalid parameter the maximum request limit is exceeded -
400 955 There is no content in your withdrawal request, please check your input - The post body of request doesn't conform the API request specification
400 703 Operation failed order_id must start with {ORDERID_PREFIX} The prefix of order_id is incorrect
400 703 Operation failed order_id: {ORDER_ID} - the character \ or / is prohibited {ORDER_ID} is invalid
400 703 Operation failed order_id: {ORDER_ID} is invalid {ORDER_ID} is invalid
400 703 Operation failed order_id: {ORDER_ID} - memo is required The outgoing address of {ORDER_ID} needs memo specified
400 703 Operation failed order_id: {ORDER_ID} - destination tag is required The outgoing address of {ORDER_ID} needs destination tag specified
400 703 Operation failed order_id: {ORDER_ID} - invalid block_average_fee The block_average_fee is out of range
400 703 Operation failed order_id: {ORDER_ID} - invalid manual_fee The manual_fee is out of range
400 703 Operation failed order_id: {ORDER_ID} - from_address is required from_address is a required parameter
400 703 Operation failed order_id: {ORDER_ID} - from_address_index is required from_address_index is a required parameter
400 703 Operation failed order_id: {ORDER_ID} - from_address_index not match from_address_index is not consistent with the index of the from_address
400 703 Operation failed order_id: {ORDER_ID} - invalid from_address from_address does not exist
400 703 Operation failed order_id: {ORDER_ID} - from_address not support from_address cannot be used in non-delegated wallets
400 399 Duplicated entry: {ORDER_ID} - The {ORDER_ID} is duplicated
400 945 The max length of BNB memo is 256 chars - Reached the limit of the length of BNB memo
400 946 The max length of EOS memo is 128 chars - Reached the limit of the length of EOS memo
400 947 The max length of XRP destination tag is 20 chars - Reached the limit of the length of XRP destination tag
400 948 The max length of XLM memo is 20 chars - Reached the limit of the length of XLM memo
400 818 Destination Tag must be integer - Wrong XRP destination tag format
400 944 The max length of order id is 255 chars - Reached the limit of the length of order_id
400 703 Operation failed Detailed error message Failed to connect to authentication callback URL
400 703 Operation failed The withdrawal request has been rejected, {RESPONSE_BODY} The withdrawal request has been rejected by the authentication callback
400 703 Operation failed The withdrawal request has been rejected, unexpected response {HTTP_CODE}: {RESPONSE_BODY} The authentication callback URL returned status code other than 200 or 400
400 703 Operation failed Unrecognized response: {RESPONSE_BODY}, 'OK' expected The returned status code is 200 but the body is not OK
400 703 Operation failed request IP ({IPv4}) not in ACL The request IP not in the withdrawal ACL
400 703 Operation failed invalid amount {AMOUNT} The requested amount is not a valid number
400 703 Operation failed invalid amount decimals {AMOUNT} The decimals of the requested amount exceeds the valid range
400 955 There is no content in your withdrawal request, please check your input - No orders found in the request that may be caused by an incorrectly formatted post body
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
404 312 Policy not found no active withdrawal policy found No active withdrawal policy found
Back to top

Cancel Withdrawal Request

To cancel the withdrawal request which state is Init or Failed. The request state can be checked on web control panel or query through this API (represents state = 0 or 5 ).

Request

POST /v1/sofa/wallets/WALLET_ID/sender/transactions/ORDER_ID/cancel

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

The prefix is 888888_ in following sample request.

API
/v1/sofa/wallets/68451/sender/transactions/88888_1/cancel
Response Format

The HTTP 200 means the withdrawal request has been cancelled successfully.

Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 177 Illegal state - The {ORDER_ID} withdrawal request is not in Init or Failed state
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The {ORDER_ID} not found
Back to top

Query Latest Withdrawal Transaction State

Check the latest withdrawal transaction state of certain order ID.

The order ID is used in the withdraw assets API.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/sender/transactions/ORDER_ID

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

The prefix is 888888_ in following sample request.

API
/v1/sofa/wallets/68451/sender/transactions/888888_1
Response Format

An example of a successful response:

{
  "order_id": "888888_1",
  "address": "0xaa0cA2f9bA3A33a915a27e289C9719adB2ad7d73",
  "amount": "1.11",
  "memo": "",
  "in_chain_block": 1016603,
  "txid": "db0f3a27de564a411aeff1d2cb3234c54817de1ecc2258a510a50c5a1063d41c",
  "create_time": "2020-03-16T10:27:57Z"
}

The response includes the following parameters:

Field Type Description
order_id string The unique ID specified in sender/transactions API
address string Outgoing address
amount string Withdrawal amount
memo string Memo on blockchain
in_chain_block int64 The block that contains this transaction
txid string Transaction ID
create_time string The withdrawal time in UTC
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The {ORDER_ID} not found
Back to top

Query All Withdrawal Transaction States

Check the all withdrawal transaction states of certain order ID.

The order ID is used in the withdraw assets API.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/sender/transactions/ORDER_ID/all

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

The prefix is 888888_ in following sample request.

API
/v1/sofa/wallets/68451/sender/transactions/888888_1/all
Response Format

An example of a successful response:

The sample shows the states of a resent transaction

{
  "transactions": [
    {
      "address": "0x36a49c68EF1e3f39CDbaE2f5636C74BA10815cea",
      "amount": "0.105",
      "create_time": "2020-09-24T03:43:17Z",
      "in_chain_block": 0,
      "memo": "",
      "order_id": "888888_1",
      "state": 6,
      "txid": "0x2a8a44f1cfed9cd7b86d86170e2418566765f88c5186246f571374df218fd1a1"
    },
    {
      "address": "0x36a49c68EF1e3f39CDbaE2f5636C74BA10815cea",
      "amount": "0.105",
      "create_time": "2020-09-24T03:44:35Z",
      "in_chain_block": 8742982,
      "memo": "",
      "order_id": "888888_1",
      "state": 4,
      "txid": "0xfbeaae4b87f977bcce8ef44672e035d287b96be24e779757c1a7f598501881ef"
    }
  ]
}

The response includes the following parameters:

Field Type Description
order_id string The unique ID specified in sender/transactions API
address string Outgoing address
amount string Withdrawal amount
memo string Memo on blockchain
in_chain_block int64 The block that contains this transaction
txid string Transaction ID
create_time string The withdrawal time in UTC
state int Refer to Transaction State Definition
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The {ORDER_ID} not found
Back to top

Query Withdrawal Transaction Event Logs

Query event logs of a withdrawal transaction by transaction hash. Only EVM Compatible Currencies are supported.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/sender/transactions/eventlog?txid=TXID

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API with parameters
/v1/sofa/wallets/345312/sender/transactions/eventlog?txid=0xe82f0be9b30d840eca64e28e6f7562b7352b3b54519a7e63fb8f6d4609194bb9

The request includes the following parameters:

Query Parameters
Field Type Note Description
txid string required Representing the transaction hash to query the event log
Response Format

An example of a successful response:

{
  "logs": [
    {
      "address": "0xeCb258697e1A4B1fE11A43fC93bD4907f1EC8c04",
      "block_hash": "0x37b6b94b8fac1eb810ddda89ceedabd37f1017f671fe41a245dc6558a25cb4bf",
      "block_number": 11173598,
      "data": "000000000000000000000000000000000000000000000000000000003b9aca00",
      "index": 0,
      "removed": false,
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "0x000000000000000000000000a952d7fc7965bec3cb03c79084236534ee2ab3cd",
        "0x000000000000000000000000d5909bacfc1fad78e4e45e9e2fef8b4e61c8fd0d"
      ],
      "tx_hash": "0xe82f0be9b30d840eca64e28e6f7562b7352b3b54519a7e63fb8f6d4609194bb9",
      "tx_index": 0
    }
  ]
}

The response includes the following parameters:

Field Type Description
logs array The event logs
address string From which this event originated from
block_hash string Hash of the block where this transaction was in
block_number uint64 Block number where this transaction was in
data string The data containing non-indexed log parameter
index uint Integer of the event index position in the block
removed boolean Indicate the log is removed (due to chain reorg)
topics array An array of values which must each appear in the log entries
tx_hash string Hash of the transaction
tx_index uint Integer of the transactions index position in the block
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Missing necessary parameters
400 112 Invalid parameter {TXID} not found No relevant withdrawal request to TXID
400 112 Invalid parameter {TXID} not in blockchain Only in-chain withdrawal transactions allowed to query event log
400 303 Invalid currency - Not supported cryptocurrency to query event log
Back to top

Query Withdrawal Wallet Balance

Get the withdrawal wallet balance. Facilitate to establish a real-time balance monitoring mechanism.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/sender/balance

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/632543/sender/balance
Response Format

An example of a successful response:

{
  "currency": 60,
  "wallet_address": "0xaa0cA2f9bA3A33a915a27e289C9719adB2ad7d73",
  "token_address": "",
  "balance": "0.619673333517576",
  "token_balance": "",
  "unconfirm_balance": "0",
  "unconfirm_token_balance": ""
}

The response includes the following parameters:

Field Type Description
currency int64 Registered coin types. Refer to Currency Definition
wallet_address string Wallet address
token_address string Token contract address
balance string Withdrawal wallet balance
token_balance string Withdrawal wallet token balance
unconfirm_balance string Unconfirmed withdrawal wallet balance
unconfirm_token_balance string Unconfirmed withdrawal wallet token balance
err_reason string Error message if fail to get balance

The currencies that support the unconfirmed balance are BTC, LTC, ETH, BCH, BSV, DASH

Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Query Withdrawal Callback Detail

Query the detailed information of the withdrawal callback by the order ID.

This API only provides in-chain transactions query, for those not in-chain transactions use Query All Withdrawal Transaction States API instead.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/sender/notifications/order_id/ORDER_ID

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

The prefix is 888888_ in following sample request.

API
/v1/sofa/wallets/68451/sender/notifications/order_id/888888_1
Response Format

An example of a successful response:

{
  "notification": {
    "addon": {},
    "amount": "100000000000000",
    "block_height": 7813953,
    "broadcast_at": 1588211126,
    "chain_at": 1588211126,
    "confirm_blocks": 109490,
    "currency": "ETH",
    "fees": "21000000000000",
    "from_address": "0xaa0cA2f9bA3A33a915a27e289C9719adB2ad7d73",
    "memo": "",
    "order_id": "888888_1",
    "processing_state": 2,
    "serial": 90000000554,
    "state": 3,
    "tindex": 30,
    "to_address": "0x60589A749AAC632e9A830c8aBE042D1899d8Dd15",
    "txid": "0x471c11f139ce1a7e0627a05cea50d64e47e797c94fd72025f1978cc919e07aa9",
    "type": 2,
    "vout_index": 0,
    "wallet_id": 68451
  }
}

The response includes the following parameters:

Field Type Description
notification object Refer to Callback Definition
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The wallet is not allowed to perform this request or the {ORDER_ID} is not found
Back to top

Set Withdrawal Request ACL

Set an authorized IP to the withdrawal request ACL dynamically.

If a static ACL has been set in web control panel, the API will fail.

Request

POST /v1/sofa/wallets/WALLET_ID/sender/transactions/acl

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/632543/sender/transactions/acl
Post body
{
  "acl": "192.168.101.55"
}

The request includes the following parameters:

Post body
Field Type Note Description
acl string requried Specify an authorized IP in IPv4 format
Response Format

An example of a successful response:

{
  "result": 1
}

The response includes the following parameters:

Field Type Description
result int Specify a successful API call
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The wallet is invalid to perform this API call
400 180 Invalid format - The acl field is empty or does not conform to the IPv4 format
400 180 Operation failed ACL has been set via web The static ACL is not empty
Back to top

Resend Withdrawal Callbacks

The callback handler can call this API to resend pending, risk-controlled or failed withdrawal callbacks.

Refer to Callback Integration for callback rules.

The resend operation could be requested on the web control panel as well.

Request

POST /v1/sofa/wallets/WALLET_ID/sender/notifications/manual

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/55743/sender/notifications/manual
Post body
{
  "notification_id": 0
}

The request includes the following parameters:

Post body
Field Type Note Description
notification_id int64 required, 0 means all Specify callback ID to resend

This ID equal to the serial field of callback data.

Response Format

An example of a successful response:

{
  "count": 3
}

The response includes the following parameters:

Field Type Description
count int Count of callbacks just resent
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Query Withdrawal Whitelist Configuration

Query the whitelist configuration of the withdrawal wallet.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/sender/whitelist/config

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/55743/sender/whitelist/config
Response Format

An example of a successful response:

{
  "effective_latency": 0,
  "whitelist_check": true
}

The response includes the following parameters:

Field Type Description
effective_latency int64 The effective latency of the whitelist entry, 0 means the whitelist entry will take effect immediately.
whitelist_check boolean Indicate whether the withdrawal wallet has enabled whitelist checking.
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Add Withdrawal Whitelist Entry

Add an outgoing address to the withdrawal wallet's whitelist.

Request

POST /v1/sofa/wallets/WALLET_ID/sender/whitelist

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/55743/sender/whitelist
Post body
{
  "items": [
    {
      "address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
      "memo": "865314",
      "user_id": "USER001"
    }
  ]
}

The request includes the following parameters:

Post body
Field Type Note Description
items array required Specify the whitelist entries
address string required The outgoing address
memo string optional The memo of the outgoing address
user_id string optional, max length 255 The custom user ID of the outgoing address
Response Format

An example of a successful response:

{
  "added_items": [
    {
      "address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
      "memo": "865314",
      "user_id": "USER001"
    }
  ]
}

The response includes the following parameters:

Field Type Description
added_items array Array of added whitelist entries
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body
400 703 Operation failed invalid address: {INVALID_ADDRESS} The address format does not comply with the cryptocurrency specification
400 703 Operation failed invalid user id: {INVALID_USER_ID} The length of the user ID exceeds 255 characters
400 703 Operation failed this wallet does not support memo The cryptocurrency does not support memo
400 945 The max length of BNB memo is 256 chars - Reached the limit of the length of BNB memo
400 946 The max length of EOS memo is 128 chars - Reached the limit of the length of EOS memo
400 947 The max length of XRP destination tag is 20 chars - Reached the limit of the length of XRP destination tag
400 948 The max length of XLM memo is 20 chars - Reached the limit of the length of XLM memo
400 818 Destination Tag must be integer - Wrong XRP destination tag format
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Remove Withdrawal Whitelist Entry

Remove an outgoing address from the withdrawal wallet's whitelist.

Request

DELETE /v1/sofa/wallets/WALLET_ID/sender/whitelist

WALLET_ID must be a withdrawal wallet ID

Only the entries exactly matches all the fields will be removed.

Request Format

An example of the request:

API
/v1/sofa/wallets/55743/sender/whitelist
Post body
{
  "items": [
    {
      "address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
      "memo": "865314",
      "user_id": "USER001"
    }
  ]
}

The request includes the following parameters:

Post body
Field Type Note Description
items array required Specify the whitelist entries
address string required The outgoing address
memo string optional The memo of the outgoing address
user_id string optional The custom user ID of the outgoing address
Response Format

An example of a successful response:

{
  "removed_items": [
    {
      "address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
      "memo": "865314",
      "user_id": "USER001"
    }
  ]
}

The response includes the following parameters:

Field Type Description
removed_items array Array of removed whitelist entries
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Check Withdrawal Whitelist

Check the withdrawal whitelist entry status in the withdrawal whitelist.

Request

VIEW POST /v1/sofa/wallets/WALLET_ID/sender/whitelist/check

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/557432/sender/whitelist/check
Post body
{
  "address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
  "memo": "865314",
  "user_id": "USER001"
}

The request includes the following parameters:

Post body
Field Type Note Description
address string required The inquiry whitelist entry address
memo string optional The memo of the whitelist entry
user_id string optional The custom user ID of the whitelist entry
Response Format

An example of a successful response:

{
  "address": "0x79D6660b2aB1d37AD5D11C2ca2B3EBba7Efd13F6",
  "create_time": "2020-12-30T13:09:39Z",
  "effective": true,
  "effective_time": "2020-12-30T13:09:39Z",
  "memo": "",
  "state": 1,
  "update_time": "2020-12-30T13:09:39Z",
  "user_id": "USER001"
}

The response includes the following parameters:

Field Type Description
address string The inquiry whitelist entry address
create_time string The creation time in UTC
effective boolean Indicate whether the whitelist entry has taken effect
effective_time string The effective time in UTC
memo string The memo of the whitelist entry
state int 1 means the entry is active, 2 means the entry is removed
update_time string Last modification time in UTC
user_id string The custom user ID of the whitelist entry
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body
400 703 Operation failed not found Cannot find the inquiry whitelist entry
400 703 Operation failed invalid address: {INVALID_ADDRESS} The address format does not comply with the cryptocurrency specification
400 703 Operation failed invalid user id: {INVALID_USER_ID} The length of the user ID exceeds 255 characters
400 703 Operation failed this wallet does not support memo The cryptocurrency does not support memo
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Query Withdrawal Whitelist

Used to query some kind of callbacks within a time interval.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/sender/whitelist?from_time=from&to_time=to&start_index=offset&request_number=count&state=state

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/557432/sender/whitelist

The request includes the following parameters:

Query Parameters
Field Type Note Description
from_time int64 optional, default 0 Start date (unix time in UTC)
to_time int64 optional, default current time End date (unix time in UTC)
start_index int64 optional, default 0 The offset to the first entry
request_number int64 optional, default 1000, max 2000 The count to request
state int optional, default -1 Use 1 to query the active entries and 2 to query the removed entries, -1 means all entries
Response Format

An example of a successful response:

{
  "items": [
    {
      "address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
      "create_time": "2020-12-30T06:02:25Z",
      "effective": false,
      "effective_time": "2020-12-30T13:27:37Z",
      "memo": "",
      "state": 1,
      "update_time": "2020-12-30T06:02:25Z",
      "user_id": "USER001"
    }
  ],
  "total_count": 1
}

The response includes the following parameters:

Field Type Description
items array Arrary of the whitelist entries
address string The whitelist entry address
create_time string The creation time in UTC
effective boolean Indicate whether the whitelist entry has taken effect
effective_time string The effective time in UTC
memo string The memo of the whitelist entry
state int 1 means the entry is active, 2 means the entry is removed
update_time string Last modification time in UTC
user_id string The custom user ID of the whitelist entry
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
Back to top

Query Withdrawal Wallet Transaction History

Get transaction history of withdrawal wallets.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/sender/transactions?from_time=from&to_time=to&start_index=start&request_number=count

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API with parameters
/v1/sofa/wallets/345312/sender/transactions?from_time=1559664000&to_time=1562255999&start_index=0&request_number=10

The request includes the following parameters:

Query Parameters
Field Type Note Description
from_time int64 optional, default 0 Start date (unix time in UTC)
to_time int64 optional, default current time End date (unix time in UTC)
start_index int optional, default 0 Index of starting transaction record
request_number int optional, default 10, max 500 Count of returning transaction record
Response Format

An example of a successful response:

{
  "total_count": 169,
  "transactions": [
    {
      "amount": "0.1",
      "block_height": 10813730,
      "block_time": "2021-08-11T06:13:01Z",
      "blocklist_tags": [],
      "fee": "0.000693",
      "from_address": "0xaa0cA2f9bA3A33a915a27e289C9719adB2ad7d73",
      "memo": "",
      "out": true,
      "source": "",
      "state": 1,
      "to_address": "0x79D6660b2aB1d37AD5D11C2ca2B3EBba7Efd13F6",
      "txid": "0xe3607325e3b7c0190089d1fb41ce9fa059858c6b2e5dd220e55ba46707fc38f0"
    },
    {
      "amount": "1",
      "block_height": 10811102,
      "block_time": "2021-08-10T17:24:21Z",
      "blocklist_tags": [],
      "fee": "0.000021",
      "from_address": "0xaa0cA2f9bA3A33a915a27e289C9719adB2ad7d73",
      "memo": "",
      "out": true,
      "source": "withdraw-api",
      "state": 1,
      "to_address": "0x8382Cc1B05649AfBe179e341179fa869C2A9862b",
      "txid": "0x19657382aa16520c32eef0dacc0f16d78e9105e83d37d126b4f6687c0d651859"
    }
  ]
}

The response includes the following parameters:

Field Type Description
total_count int Total transactions in specified date duration
transactions array Array of transaction record
txid string Transaction ID
from_address string Sender address of the transaction
to_address string Recipient address of the transaction
out boolean True means outgoing transaction
amount string Transaction amount
blocklist_tags array The tags of CYBAVO AML detection. If out is true, the to_address is tagged. Otherwise, the from_address is tagged
block_height int64 The block height
block_time time When was the transaction packed into block (in chain) in UTC time
fee string Transaction blockchain fee
memo string Memo of the transaction
source string withdraw-api means that the transaction was triggered by the withdrawal API, otherwise it was triggered from the web withdrawal UI
state int Refer to State Definition bellow

State Definition
ID Description
1 Success, the transaction status is successful
2 Failed, the transaction status is failed
3 Invalid, the transaction status is successful but is identified as invalid by the SOFA system
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - from_time or to_time is invalid
Back to top

Sign Message

Sign message, equivalent to eth_sign.

Request

POST /v1/sofa/wallets/WALLET_ID/signmessage

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/557432/signmessage
Post body
{
  "message": "This is proof that I, user A, have access to this address."
}

The request includes the following parameters:

Post body
Field Type Note Description
message string required Message to be signed
is_hex boolean optional Treat the message as a hexadecimal string that will be decoded before signing
eip155 boolean optional Sign the message in EIP-155 format
wallet_address string required, for delegated wallet Specify the delegated address for the request
index int64 required, for delegated wallet Specify the corresponding index of the wallet_address
Response Format

An example of a successful response:

{
  "signed_message": "0xf296a678ce1d577acbee25119b7be821db70e960d6e65ef73fb1e50fa832759d27d35df2dd309be07cb5a9b9f6c87f5eeae11ff56b995e0b32d6288b1039555b2a"
}

The response includes the following parameters:

Field Type Description
signed_message string Signed message
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body
400 112 Invalid parameter wallet_address is required wallet_address is a required parameter
400 703 Operation failed index not match index is not consistent with the index of the wallet_address
404 303 Invalid currency - The wallet is not allowed to perform this request
404 304 Wallet ID invalid mapped wallet not supported -
Back to top

Call Contract Read ABI

Executes a contract read ABI call.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/contract/read?contract=contract_address&data=data

Withdrawal Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API with parameters
/v1/sofa/wallets/345312/contract/read?contract=0xad6d458402f60fd3bd25163575031acdce07538d&data=0xdd62ed3e000000000000000000000000d11bd6e308b8dc1c5243d54cf41a427ca0f46943000000000000000000000000e592427a0aece92de3edee1f18e0157c05861564

The request includes the following parameters:

Query Parameters
Field Type Note Description
contract string required Representing the contract to interact with
data string requried The hash of the method signature and encoded parameters

The data must be encoded by web3.eth.abi.encodeFunctionCall() of web3.js.

Response Format

An example of a successful response:

{
  "output": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
}

The response includes the following parameters:

Field Type Description
output string The output of read ABI call

The output can be decoded by web3.eth.abi.decodeparameters() of web3.js.

Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
404 304 Wallet ID invalid wrong wallet type -
404 304 Wallet ID invalid archived wallet -
404 304 Wallet ID invalid mapped wallet not supported -
400 112 Invalid parameter - Missing necessary parameters
400 112 Operation failed invalid address: {contract_address} The contract address does not conform to the cryptocurrency format
400 112 Invalid parameter no contract policy There is no contract policy of the given wallet
400 112 Invalid parameter unsupported contract There is no contract policy of the given contract address
400 303 Invalid currency - Not supported cryptocurrency to call contract read ABI
Back to top

Arweave Sign Transaction

Sign Arweave transaction for uploading data. This API is dedicated to the Arweave withdrawal wallet.

Request

POST /v1/sofa/wallets/WALLET_ID/signtransaction

Withdrawal Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/557432/signtransaction
Post body
{
  "ar_tx": "{\"format\":2,\"id\":\"\",\"last_tx\":\"4z4iqqw4j_bBC1jXvm-pbMDg5eSYOGPjRz2fB1nsai6cVtvTd7Ucn-_Qau_bZh\",\"owner\":\"KkTVKjrry_aieBmqNOuUGtJam-3yT6zMABY89pinlcY\",\"tags\":[{\"name\":\"Q29udGVudC1UeXBl\",\"value\":\"aW1hZ2UvanBlZw\"}],\"target\":\"\",\"quantity\":\"0\",\"data\":\"\",\"data_size\":\"23782\",\"data_root\":\"Ve1yivS-iMklYK6xyPT58IeZRu-TtnAYkW5Ih4pb-S4\",\"reward\":\"73874553\",\"signature\":\"\",\"chunks\":\"\"}"
}

The request includes the following parameters:

Post body
Field Type Note Description
ar_tx string required Transaction JSON string to be signed

The owner field is the address of the withdrawal wallet. The owner field of the response is the public key of the wallet address.

Response Format

An example of a successful response:

{
  "id": "j06PW1hWTS2keWOl6X_oIKdUMV29MllMlO2rSRDhkzg",
  "signature": "v56Dgg-V--ZQANyhyc00Pgd2nywB9NFv7YOgY4ngv7WlHCydDNzlKIvTGCrJvC0xmnuQv-O4XAHM4NbQCKEOfqU8kpwPvo59lQA1yCIjQeNw3rGvlg832MvyAR71FjME5KI84vz-IcDOGpqJs-GApjPpbTren5NKfkVMA9TAnTUhd3wQafQdTdbaGnBbccuHxEFBqR3xWkjt6r2dsmtUZkyVz41MAjMJyQ8u7_131AexJXNBX0U-wDXxJ6eu6kydMPrdsYqU6no8wEEl3XTdsOmJ5J1jy9uiCyN5Ri2II2VzTvKgP8xVOquAo2EZGQLHo2nJU4sVOXHA1ZJ9l0U2ny5ZMyqqh3tFqEsk5dDwBJumoCbMo0bFOKSXiG7iez8WEi57kdLy5PJBizW5jFYITm1fXnJ8ERyk8wTHu0f1_5FQLZtinl6sbwsb_xCyy2siPYc5CpwR5u6yR7hCbBxt9WJ3nDeMfKTRk2_vnEYagC_HzMk3aG1oqohaA8_J7t8UNli8idLS7LpxTWdZuU32rIU8mv9lVpEbxjGpRQFqvwS32AUxLM6llG5svswgb38_y7GEajWZkeAuZ4-dvK7r91evzkbrKbpI_mnOGnMgPopiyCl6wEOoiJYtfo5IbAXi5YJITZ7KbwtoWh-MzJFPE_9UnZ9eXY8GKJU-mZC23NA",
  "owner": "teNsEXXHfFdY2TM-ZGpNXzAoSqNND2cZ2TW-Xnc7-yl4SjFJmMpLiYhgeunSJGaVe08ZMDCHDnYykj91E5f1ZApL7y_W3WkCDEoWeRnm69M-SUPCw35oo1HF_hvwgfnX3H14zifIWHTKJq1vxSD7y2EGRVUBn5xZlWjoUJ5Gbbn2BRDQ_Fob7x_ckTbLvDBomdTFQeAntXH99OxE9pH88SI6OkmkYzZXjYmJYaGIP6q81y6CCxfmzWdLRGNXNYimacNuJAJxh4ZsWr-tRewVPPrj3f30Iybmb_VIlhuI9r6sA_rhwyigL1qTvuXZ6b47tpY7idnU8Ea0X3KIVNt-C2flWebczWBz1pcljBtHcxrGHhewOp2gO3_I3nsm5MRwtaR1512iewsEZQj7apJe5EY6kZIG_YBRbv8YRZEhvmkHcCO4lKuNqjw9lrbsFI-atZ61z_jVeWJrBB6Lwyp9v6VOs09lsHoBDjFR9eCOy1nfn6a26iKLMPj9X5xRukvicQ5ZWUU8zbtGDskyUtvhkH4uXGNjkjE7d-WaAR4cj7Ni6mrFA2iHcqIUODpu8DR-bZ5yxENQjjIgm6Rr--v-kRltu4iEADdQBfUzY1hYOo6GtgyYLUnHPFB7IDMULyolo_31yUIAblHbNOuBF9fRue-ODY_MZKvOS1Qq7GH0_sE"
}

The response includes the following parameters:

Field Type Description
id string ID field of the signed transaction
signature string Signature filed of the signed transaction
owner string Public key of the wallet address
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body
400 112 Invalid parameter not allowed to sign asset transfer transaction The quantity or target is not empty
400 112 Invalid parameter invalid transaction format The data_size is zero or data_root is empty
404 303 Invalid currency - The wallet is not allowed to perform this request
Back to top

Deposit / Withdrawal Wallet Common API

Query Callback History

Used to query some kind of callbacks within a time interval.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/notifications?from_time=from&to_time=to&type=type

Withdrawal Wallet Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/677414/notifications?from_time=1561651200&to_time=1562255999&type=2

The request includes the following parameters:

Query Parameters
Field Type Note Description
from_time int64 optional, default 0 Start date (unix time in UTC)
to_time int64 optional, default current time End date (unix time in UTC)
type int optional, default -1 Refer to Callback Type
Response Format

An example of a successful response:

{
  "notifications": [
    {
      "type": 2,
      "serial": 90000000003,
      "order_id": "a206",
      "currency": "BNB",
      "txid": "76B8B2B1E25472FFE7B8FCE85742E0964FEDB1B679DE963FA19F430E8B287F93",
      "block_height": 25844472,
      "tindex": 2,
      "vout_index": 0,
      "amount": "15000000",
      "fees": "37500",
      "memo": "CC",
      "broadcast_at": 0,
      "chain_at": 1562234190,
      "from_address": "tbnb1f805kv6z8nq2whrcnkagjte3jjss2sxf2rfls0",
      "to_address": "tbnb1655kasahedvaeudaeq6jggr7kal8qgwygu9xqk",
      "wallet_id": 677414,
      "state": 3,
      "confirm_blocks": 1,
      "processing_state": 1,
      "addon": {}
    }
  ]
}

The response includes the following parameters:

Field Type Description
notifications array Arrary of callbacks, refer to Callback Definition
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
Back to top

Query Callback Detail

Query the detailed information of the callback by its serial ID. It can be used to reconfirm whether a deposit callback exists.

Request

VIEW POST /v1/sofa/wallets/WALLET_ID/notifications/get_by_id

Withdrawal Wallet Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/677414/notifications/get_by_id
Post body
{
  "ids": [90000000140, 90000000139]
}

The request includes the following parameters:

Post body
Field Type Note Description
ids array requried Specify the IDs for query
Response Format

An example of a successful response:

{
  "notifications": [
    {
      "type": 3,
      "serial": 90000000139,
      "order_id": "",
      "currency": "ADA",
      "txid": "35c283a6f13f5886240fe2e815bc149154ec066cd2061202318dd4e4bf8af35e",
      "block_height": 1003304,
      "tindex": 0,
      "vout_index": 0,
      "amount": "24447",
      "fees": "0",
      "memo": "",
      "broadcast_at": 1584088556,
      "chain_at": 1584088556,
      "from_address": "",
      "to_address": "37btjrVyb4KG8gKeZjJguinwdsbcRV65ngHhBUaJWf36QxiakTV3UHiNUP9arReXMZQnpRBVVdkcBB4GyiWzPRSTmg41mTzMpxgfhtfRHtaBCKJNbX",
      "wallet_id": 677414,
      "state": 3,
      "confirm_blocks": 2,
      "processing_state": 1,
      "addon": {}
    },
    {
      "type": 3,
      "serial": 90000000140,
      "order_id": "",
      "currency": "ADA",
      "txid": "fa120b6283509f0ab2b136a3ac8b613aa3ca2f36ce7c2744e122668d013cfdb5",
      "block_height": 1003305,
      "tindex": 0,
      "vout_index": 0,
      "amount": "55497180",
      "fees": "0",
      "memo": "",
      "broadcast_at": 1584088576,
      "chain_at": 1584088576,
      "from_address": "",
      "to_address": "37btjrVyb4KDKCyAPRUPxpGiUPWunpBAkGRX8U3h7LYzS2UrHUnEQozcCyqR2GfBVnM3frTaUNEb8DoNGo9JakrskAtaWt6vED6R6ohkmaJ2qr4oCg",
      "wallet_id": 677414,
      "state": 3,
      "confirm_blocks": 1,
      "processing_state": 1,
      "addon": {}
    }
  ]
}

The response includes the following parameters:

Field Type Description
notifications array Arrary of callbacks, refer to Callback Definition
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
Back to top

Query Wallet Synchronization Info

Get the blockchain synchronization status of a wallet.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/blocks

Withdrawal Wallet Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/677414/blocks
Response Format

An example of a successful response:

{
  "latest_block_height": 29317651,
  "synced_block_height": 28529203
}

The response includes the following parameters:

Field Type Description
latest_block_height int64 The latest block height on blockchain
synced_block_height int64 The current synced block height
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
Back to top

Query Transaction Average Fee

Query average blockchain fee within latest N blocks.

Request

VIEW POST /v1/sofa/wallets/WALLET_ID/autofee

Withdrawal Wallet Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/635718/autofee
Post body
{
  "block_num": 1
}

The request includes the following parameters:

Post body
Field Type Note Description
block_num int optional, default 1, range 1~100 Query the average blockchain fee in the last N blocks
Response Format

An example of a successful response:

{
  "auto_fee": "1"
}

The response includes the following parameters:

Field Type Description
auto_fee string Mining fee denominated in the smallest cryptocurrency unit
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - The block_num is out of range
Back to top

Batch Query Transaction Average Fees

Batch Query average blockchain fee within latest N blocks.

Request

VIEW POST /v1/sofa/wallets/WALLET_ID/autofees

Withdrawal Wallet Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/854714/autofees
Post body
{
  "block_nums": [1, 5, 10]
}

The request includes the following parameters:

Post body
Field Type Note Description
block_nums array required, max 5 entries, each entry is range 1~100 Batch query the average blockchain fee in the last N blocks
Response Format

An example of a successful response:

{
  "auto_fees": [
    {
      "auto_fee": "49000000000",
      "block_num": 1
    },
    {
      "auto_fee": "49000000000",
      "block_num": 5
    },
    {
      "auto_fee": "38000000000",
      "block_num": 10
    }
  ]
}

The response includes the following parameters:

Field Type Description
auto_fees array Result of the inquiry
block_num int Inquiry block number
auto_fee string Mining fee denominated in the smallest cryptocurrency unit
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Exceeds 5 entries or each entry not in range
Back to top

Vault Wallet API

Query Vault Wallet Transaction History

Get transaction history of vault wallets.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/transactions?from_time=from&to_time=to&start_index=start&request_number=count&state=state

Vault Wallet

Request Format

An example of the request:

API with parameters
/v1/sofa/wallets/488471/transactions?from_time=1559664000&to_time=1562255999&start_index=0&request_number=1

The request includes the following parameters:

Query Parameters
Field Type Note Description
from_time int64 optional, default 0 Start date (unix time in UTC)
to_time int64 optional, default current time End date (unix time in UTC)
start_index int optional, default 0 Index of starting transaction record
request_number int optional, default 1000, max 5000 Count of returning transaction record
state int optional, default -1 Refer to Transaction State Filter Definition bellow

Transaction State Filter Definition
ID Description
0 WaitApproval
1 Rejected
2 Approved
3 Failed
4 NextLevel
5 Cancelled
6 BatchDone
-1 All states (for inquiry)
Response Format

An example of a successful response:

{
  "transaction_count": 3,
  "transaction_item": [
    {
      "issue_user_id": 3,
      "issue_user_name": "wallet owner (user@gmail.com)",
      "description": "TO SND",
      "wallet_id": 488471,
      "wallet_name": "BNB I",
      "wallet_address": "tbnb1655kasahedvaeudaeq6jggr7kal8qgwygu9xqk",
      "token_address": "",
      "txid": "3E6D61D1D39FA5DD3B86C2C28FFAD3D98CD7AFDB62346468D3C4FFE710CAAF85",
      "currency": 714,
      "currency_name": "BNB",
      "outgoing_address": "tbnb1f805kv6z8nq2whrcnkagjte3jjss2sxf2rfls0",
      "outgoing_address_name": "BNB SND",
      "amount": "2",
      "fee": "0",
      "txno": 100087,
      "approval_item": [
        {
          "approval_id": 3,
          "approval_user": "wallet owner (user@gmail.com)",
          "approval_time": 1562210142,
          "user_message": "",
          "level": 0,
          "owner": 1,
          "confirm": 1,
          "state": 2,
          "error_code": 0
        }
      ],
      "state": 2,
      "create_time": 1562210129,
      "transaction_time": 1562210142,
      "scheduled_name": "",
      "transaction_type": 0,
      "eos_transaction_type": 0,
      "real_amount": "2",
      "chain_fee": "0.000375",
      "platform_fee": "0",
      "tx_category": "",
      "memo": "TO SND"
    }
  ]
}

The response includes the following parameters:

Field Type Description
transaction_count int Total transactions in specified date duration
transaction_item array Array of transaction record

Refer to Currency Definition or here for more detailed currency definitions

Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
Back to top

Query Vault Wallet Balance

Get the vault wallet balance. Facilitate to establish a real-time balance monitoring mechanism.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/vault/balance

Vault Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/488471/vault/balance
Response Format

An example of a successful response:

BTC vault wallet

{
  "balance": "0.00009798",
  "currency": 0,
  "token_address": "",
  "token_balance": "",
  "unconfirm_balance": "0",
  "unconfirm_token_balance": "",
  "wallet_address": "2Mw1iJnQvAt3hNEvEZKdHkij8TNtzjaF3LH"
}

USDT-Omni vault wallet that mapping to above BTC vault wallet

{
  "balance": "0.00009798",
  "currency": 0,
  "token_address": "31",
  "token_balance": "0.1",
  "unconfirm_balance": "0",
  "unconfirm_token_balance": "",
  "wallet_address": "2Mw1iJnQvAt3hNEvEZKdHkij8TNtzjaF3LH"
}

The response includes the following parameters:

Field Type Description
currency int64 Registered coin types. Refer to Currency Definition
wallet_address string Wallet address
token_address string Token contract address
balance string Withdrawal wallet balance
token_balance string Withdrawal wallet token balance
unconfirm_balance string Unconfirmed withdrawal wallet balance
unconfirm_token_balance string Unconfirmed withdrawal wallet token balance

The currencies that support the unconfirmed balance are BTC, LTC, ETH, BCH, BSV, DASH

Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
403 385 API Secret not valid - Invalid API code permission
Back to top

Common API

Activate API Code

Activate the API code of a certain wallet. Once activated, the currently activated API code will immediately become invalid.

Request

POST /v1/sofa/wallets/WALLET_ID/apisecret/activate

Withdrawal Wallet Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/488471/apisecret/activate
Response Format

An example of a successful response:

{
  "api_code": "4PcdE9VjXfrk7WjC1",
  "exp": 1609646716
}

The response includes the following parameters:

Field Type Description
api_code string The activated API code
exp int64 The API code expiration unix time in UTC
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
Back to top

Query API Code Status

Query the API code info of a certain wallet. Use the inactivated API code in any request will activate it. Once activated, the currently activated API code will immediately become invalid.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/apisecret

Withdrawal Wallet Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/488471/apisecret
Response Format

An example of a successful response:

{
  "valid": {
    "api_code": "H4Q6xFZgiTZb37GN",
    "exp": 1583144863
  },
  "inactivated": {
    "api_code": "32PmGCjNzXda4mNHX"
  }
}

The response includes the following parameters:

Field Type Description
valid object The activated API code
inactivated object Not active API code
api_code string The API code for querying wallet
exp int64 The API code expiration unix time in UTC

Use an invalid API-CODE, the caller will get a 403 Forbidden error.

Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
Back to top

Refresh API Code

Use paired refresh code to acquire the new inactive API code/secret of the wallet.

Request

POST /v1/sofa/wallets/WALLET_ID/refreshsecret

Withdrawal Wallet Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/357818/refreshsecret
Post body
{
  "refresh_code": "3EbaSPUpKzHJ9wYgYZqy6W4g43NT365bm9vtTfYhMPra"
}

The request includes the following parameters:

Post body
Field Type Note Description
refresh_code string required The corresponding refresh code of the API code specified in the X-API-CODE header
Response Format

An example of a successful response:

{
  "api_code": "4QjbY3qES4tEh19PU",
  "api_secret": "3jC1qjr4mrKxfoXkxoN27Uhmbm1E",
  "refresh_code": "HcN17gxZ3ojrBYSXnjKsU9Pun8krP6J9Pn678k4rZ13m"
}

The response includes the following parameters:

Field Type Description
api_code string The new inactive API code
api_secret string The API secret
refresh_code string The paired refresh code
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body or the refresh code is invalid
Back to top

Query Wallet Info

Get wallet basic information.

Request

VIEW GET /v1/sofa/wallets/WALLET_ID/info

Withdrawal Wallet Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/488471/info
Response Format

An example of a successful response:

{
  "currency": 60,
  "currency_name": "ETH",
  "address": "0xd11Bd6E308b8DC1c5243D54cf41A427Ca0F46943",
  "token_name": "TTF TOKEN",
  "token_symbol": "TTF",
  "token_contract_address": "0xd0ee17a4e1866c1ac53a54cc2cd4dd64b503cf40",
  "token_decimals": "18"
}

The response includes the following parameters:

Field Type Description
currency int64 Registered coin types. Refer to Currency Definition
currency_name string Name of currency
address string Wallet address

Refer to here for more detailed currency definitions

If WALLET_ID is a token wallet, the following fields present:

Field Type Description
token_name string Token name
token_symbol string Token symbol
token_contract_address string Token contract address
token_decimals string Token decimals
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
Back to top

Verify Addresses

Check if the address conforms to the wallet cryptocurrency address format (for example, ETH must have the prefix 0x, BTC should start with 1, 3 or bc1, etc).

If the wallet's cryptocurrency is BNB or XRP, there will be a must_need_memo flag to indicate whether the address needs a memo / destination tag when transferring cryptocurrency to that address.

Request

VIEW POST /v1/sofa/wallets/WALLET_ID/addresses/verify

Wallet ID must be a deposit or withdraw wallet's ID

Request Format

An example of the request:

API
/v1/sofa/wallets/488471/addresses/verify
Post body
{
  "addresses": [
    "0x635B4764D1939DfAcD3a8014726159abC277BecC",
    "1CK6KHY6MHgYvmRQ4PAafKYDrg1ejbH1cE"
  ]
}

The request includes the following parameters:

Post body
Field Type Note Description
addresses array requried Specify the address for verification
Response Format

An example of a successful response:

{
  "result": [
    {
      "address": "0x635B4764D1939DfAcD3a8014726159abC277BecC",
      "valid": true,
      "must_need_memo": false
    },
    {
      "address": "1CK6KHY6MHgYvmRQ4PAafKYDrg1ejbH1cE",
      "valid": false,
      "must_need_memo": false
    }
  ]
}

The response includes the following parameters:

Field Type Description
result array Array of addresses' verification result
must_need_memo boolean Indicate whether the address needs a memo / destination tag when transferring cryptocurrency to that address
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body
Back to top

Inspect Callback Endpoint

Use to inspect the notification and withdrawal authentication endpoint.

Request

VIEW POST /v1/sofa/wallets/WALLET_ID/notifications/inspect

Withdrawal Wallet Deposit Wallet Deposit-withdrawal Wallet Delegated Wallet

Request Format

An example of the request:

API
/v1/sofa/wallets/896541/notifications/inspect
Post body
{
  "test_number": 102999
}

The request includes the following parameters:

Post body
Field Type Note Description
test_number int64 requried The test number will be sent to the notification endpoint in the format {"msg":"CONNECTION TEST","server_time":1622195270,"client_ip":"xxx.xxx.xxx.xxx","test_number":102999}.
Response Format

An example of a successful response:

{
  "server_time": 1622195253,
  "client_ip": "::1",
  "notification_endpoint": {
    "url": "http%3A%2F%2Flocalhost%3A8889%2Fv1%2Fmock%2Fwallets%2Fcallback",
    "status_code": 400,
    "response": "NDAw"
  },
  "withdrawal_authentication_endpoint": {
    "error": "no endpoint found"
  }
}

The response includes the following parameters:

Field Type Description
server_time int64 Current server unix time in UTC
client_ip string The request client IP
notification_endpoint struct Specify the test result of notification endpoint
withdrawal_authentication_endpoint struct Specify the test result of withdrawal authentication endpoint
url string The escaped endpoint URL
status_code int The HTTP response status code from endpoint
response string The base64 encoded response from endpoint
error string Specify the connection error if any
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 112 Invalid parameter - Malformatted post body
Back to top

Read-only API code API

List Wallets

List all wallets can be accessed by the inquiry read-only API code.

Request

VIEW GET /v1/sofa/wallets/readonly/walletlist

The API code must be a read-only API code. Use wallet ID 0 to register API code with the mock server.

Request Format

An example of the request:

API
/v1/sofa/wallets/readonly/walletlist
Response Format

An example of a successful response:

{
  "total": 2,
  "wallets": [
    {
      "address": "2NAnSkEp6SpUPLsdP3ChvN6K5qPMZyoB3RF",
      "currency": 0,
      "currency_name": "BTC",
      "decimals": "8",
      "type": 2,
      "wallet_id": 101645
    },
    {
      "address": "0x85AfD8F88C0347aFF89AFc6C0749322719396616",
      "currency": 60,
      "currency_name": "ETH",
      "decimals": "18",
      "token_contract_address": "0xdf2ce4af00b10644d00316b3d99e029d82d5d2f3",
      "token_decimals": "18",
      "token_name": "JGB2",
      "token_symbol": "JGB2",
      "type": 0,
      "wallet_id": 118970
    }
  ]
}

The response includes the following parameters:

Field Type Description
address string Wallet address
currency int64 Registered coin types. Refer to Currency Definition
currency_name string Name of currency
decimals string Decimals of currency
type int Wallet Type. Refer to Wallet Type Definition
wallet_id int64 Wallet ID
token_name string Token name
token_symbol string Token symbol
token_contract_address string Token contract address
token_decimals string Token decimals
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
Back to top

Query Wallets Balance

Query balance of all wallets can be accessed by the inquiry read-only API code.

Request

VIEW GET /v1/sofa/wallets/readonly/walletlist/balances?type=type&start_index=start_index&request_number=request_number

The API code must be a read-only API code. Use wallet ID 0 to register API code with the mock server.

Request Format

An example of the request:

API
/v1/sofa/wallets/readonly/walletlist/balances

The request includes the following parameters:

Field Type Note Description
type int optional, default -1 Specify the wallet type want to query. Supports Vault, Deposit and Withdrawal wallet type. Refer to Wallet Type Definition
start_index int optional, default 0 Specify start index
request_number int optional, default 50, max 100 Request count
Response Format

An example of a successful response:

{
  "total": 104,
  "wallet_balances": [
    {
      "balance": "1",
      "type": 0,
      "wallet_id": 417702
    },
    {
      "balance": "0.35673727953125",
      "token_balance": "0.00000099",
      "type": 0,
      "wallet_id": 426493
    },
    {
      "balance": "4.661838507219943297",
      "token_id_balances": [
        {
          "balance": "4",
          "token_id": "2001"
        },
        {
          "balance": "50000",
          "token_id": "2004"
        },
        {
          "balance": "0",
          "token_id": "2005"
        }
      ],
      "type": 0,
      "wallet_id": 661159
    },
    {
      "balance": "0.010000000000000000",
      "pool_balance": "0.414979",
      "type": 2,
      "wallet_id": 520474
    },
    {
      "balance": "27.46735753510800289",
      "token_balance": "0",
      "type": 3,
      "wallet_id": 100587
    }
  ]
}

The response includes the following parameters:

Field Type Description
wallet_id int64 Wallet ID
wallet_name string Wallet Name
address string Wallet address
currency int64 Registered coin types. Refer to Currency Definition
currency_name string Name of currency
decimals string Decimals of currency
type int Wallet Type. Refer to Wallet Type Definition
token_name string Token name
token_symbol string Token symbol
token_contract_address string Token contract address
token_decimals string Token decimals
error boolean Set to true if the balance query fails
balance string Wallet balance. For token wallet this is the mapped wallet's balance.
unconfirm_balance string Unconfirmed wallet balance. For token wallet this is the mapped wallet's unconfirmed balance.
token_balance string Wallet token balance
unconfirm_token_balance string Unconfirmed wallet token balance
pool_balance string Wallet pool address balance
pool_unconfirm_token_balance string Wallet Pool address unconfirmed balance
token_id_balances array For ERC1155, ERC721 token wallet

Refer to Support Unconfirmed Balance Currency for the currencies that support the unconfirmed balance.

For delegated ERC721 and ERC1155 token wallets, use the Query Delegated Address Balance API to query detailed token_id_balances information.

Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid ID - No wallet ID found
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
Back to top

Query Currency Prices

Query the prices of all currencies available in the SOFA system.

The prices provided by the API are averages for some exchanges and may not be real-time and accurate, so please be aware of the risk of possible price fluctuations when using the API.

Request

VIEW GET /v1/sofa/currency/prices?convert=currency

The API code must be a read-only API code. Use wallet ID 0 to register API code with the mock server.

Request Format

An example of the request:

API
/v1/sofa/currency/prices?convert=USD,GBP

The request includes the following parameters:

Field Type Note Description
convert string optional, default USD The legal tender to be converted, concats with ","

All legal tender currencies supported are AUD, BRL, CAD, EUR, GBP, INR, JPY, KRW, NZD, PLN, RUB, SEK, SGD, THB, TWD, USD, ZAR.

Response Format

An example of a successful response:

{
  "currency_prices": [
    {
      "currency": 145,
      "currency_symbol": "BCH",
      "prices": {
        "GBP": 238.67160135,
        "USD": 323.05
      }
    },
    {
      "currency": 0,
      "currency_symbol": "BTC",
      "prices": {
        "GBP": 30967.87854042,
        "USD": 41916.06
      }
    },
    {
      "currency": 60,
      "currency_symbol": "ETH",
      "prices": {
        "GBP": 2116.74115956,
        "USD": 2865.08
      }
    }
  ],
  "last_refresh_attempt_time": 1644811648,
  "last_refresh_success_time": 1644811650
}

The response includes the following parameters:

Field Type Description
currency int64 Registered coin types. Refer to Currency Definition
token_address string Token contract address
prices key-value Currency-Price pair
last_refresh_attempt_time int64 Last attempt to update prices (unix time in UTC)
last_refresh_success_time int64 Last successful price update time (unix time in UTC)
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
Back to top

Query Contract Token Meta

Used to query token meta information for a specific contract.

Request

VIEW POST /v1/sofa/currency/CURRENCY/contract/get-multiple-tokenuri

The API code must be a read-only API code. Use wallet ID 0 to register API code with the mock server.

All EVM compatible currencies are supported. Refer to EVM Compatible Currency.

Request Format

An example of the request:

API
/v1/sofa/currency/60/contract/get-multiple-tokenuri
Post body
{
  "requests": [
    {
      "token_address": "0x9fceceda8a781e493a0eba6a59c6e6c731fd5ee5",
      "token_id": "1"
    }
  ]
}

The request includes the following parameters:

Post body
Field Type Note Description
requests array requried Specify all inquiry contracts
token_address string requried Specify token contract address
token_id string requried if token_adress is a ERC1155 contract Specify token ID in an ERC1155 contract
Response Format

An example of a successful response:

{
  "responses": [
    {
      "error_message": null,
      "token_address": "0x9fceceda8a781e493a0eba6a59c6e6c731fd5ee5",
      "token_id": "1",
      "uri_info": {
        "description": "Elementos character",
        "image": "https://gateway.pinata.cloud/ipfs/QmQRzm4tzvboKqseZFWV1MYjbwVQFeeQfyc4Vf9EqEnQHm",
        "name": 1,
        "token_uri": "https://gateway.pinata.cloud/ipfs/QmNW6R5J5vTxcRHpiMP4KNwRbtUyJExH6buXqhHLUwfHum"
      }
    }
  ]
}

The response includes the following parameters:

Field Type Description
error_message string Description of any errors that occurred
token_address string Inquiry token contract
token_id string Inquiry token ID
uri_info struct Meta information, please refer to EIP-721, EIP-1155.
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
400 965 Not Supported - Not supported currency
Back to top

Query Service Health Status

Used to query service health status.

Request

VIEW GET /v1/sofa/healthcheck

The API code must be a read-only API code. Use wallet ID 0 to register API code with the mock server.

Request Format

An example of the request:

API
/v1/sofa/healthcheck
Response Format

An example of a successful response:

{
  "cc_state": 1,
  "ww_state": 1,
  "kms_state": 1,
  "mpc_enabled": true,
  "mpc_state": 1
}

The response includes the following parameters:

Field Type Description
cc_state int 1 means the service is live, 0 means the service is down
ww_state int 1 means the service is live, 0 means the service is down
kms_state int 1 means the service is live, 0 means the service is down
mpc_enabled boolean true means MPC enabled, false means no MPC
mpc_state int 1 means the service is live, 0 means the service is down
Error Code
HTTP Code Error Code Error Message Description
403 - Forbidden. Header not found - Missing X-API-CODE, X-CHECKSUM header or query param t
403 - Forbidden. Invalid timestamp - The timestamp t is not in the valid time range
403 - Forbidden. Invalid checksum - The request is considered a replay request
403 - Forbidden. Invalid API code - X-API-CODE header contains invalid API code
403 - Invalid API code for wallet {WALLET_ID} - The API code mismatched
403 - Forbidden. Checksum unmatch - X-CHECKSUM header contains wrong checksum
403 - Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) - Send requests too frequently
403 385 API Secret not valid - Invalid API code permission
Back to top

Mock Server

How to compile

  • Put sample code to {YOUR_GO_PATH}/github.com/cybavo/SOFA_MOCK_SERVER
  • Execute
    • go mod vendor
    • go build ./mockserver.go
    • ./mockserver

Setup configuration

Configure CYBAVO API server URL in mockserver.app.conf

api_server_url="BACKEND_SERVER_URL"

Put wallet API code/secret into mock server

  • Get API code/secret on web control panel
    • API_CODE, API_SECRET, WALLET_ID
  • Put API code/secret to mock server's database
  • For the read-only API code/secret, use wallet ID 0 to register.
curl -X POST -H "Content-Type: application/json" -d '{"api_code":"API_CODE","api_secret":"API_SECRET"}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/apitoken

Register mock server callback URL

Operate on web control panel

Notification Callback URL

http://localhost:8889/v1/mock/wallets/callback

Withdrawal Authentication Callback URL

http://localhost:8889/v1/mock/wallets/withdrawal/callback

The withdrawal authentication callback URL once set, every withdrawal request will callback this URL to get authentication to proceed withdrawal request.

Refer to WithdrawalCallback() function in mock server OuterController.go

Back to top

cURL Testing Commands

Create Deposit Addresses

For BNB, XLM, XRP or EOS wallet:

curl -X POST -H "Content-Type: application/json" -d '{"count":2,"memos":["10001","10002"]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses

For wallet excepts BNB, XLM, XRP and EOS:

curl -X POST -H "Content-Type: application/json" -d '{"count":2}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses

Query Deposit Addresses

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses?start_index=0&request_number=1000

Query Deployed Contract Deposit Addresses

curl 'http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/contract_txid?txids={TXID1},{TXID2}'

Query Pool Address

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/pooladdress

Query Pool Address Balance

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/pooladdress/balance

Query Invalid Deposit Addresses

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/invalid-deposit

Query Deposit Callback Detail

curl 'http://localhost:8889/v1/mock/wallets/{WALLET_ID}/receiver/notifications/txid/{TX_ID}/{VOUT_INDEX}'

Resend Deposit/Collection Callbacks

curl -X POST -H "Content-Type: application/json" -d '{"notification_id":0}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/collection/notifications/manual

Query Deposit Wallet Balance

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/receiver/balance

Update Deposit Address Label

curl -X POST -H "Content-Type: application/json" -d '{"address":"0x2B974a3e0b491bB26e0bF146E6cDaC36EFD574a","label":"take-some-notes"}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/label

Query Deposit Address Label

curl -X POST -H "Content-Type: application/json" -d '{"addresses":["0x2B974a3De0b491bB26e0bF146E6cDaC36EFD574a","0xF401AC94D9672e79c68e56A6f822b666E5A7d644"]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/get_labels

Query Delegated Address Balance

curl -X POST -H "Content-Type: application/json" -d '{"addresses":["0x6A2969E4496d5b27967a68b411D7e0218943c1B6","0x1EA22Ed0347E6C9f852cfcBEFE752A026450164b","0x2baB9B3af6041960322a248d5315850fc79a3881"]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/receiver/get-balances

Verify Deposit Addresses

curl -X POST -H "Content-Type: application/json" -d '{"addresses":["0x46d4AD967F68253f61D45a044dC7dC7B13E5A4B3","0x107FF19Ea5fB7de78392e7AcC2A2C7eace891bDc"]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/receiver/addresses/verify

Withdraw Assets

curl -X POST -H "Content-Type: application/json" -d '{"requests":[{"order_id":"888888_1","address":"0x60589A749AAC632e9A830c8aBE042D1899d8Dd15","amount":"0.0001","memo":"memo-001","user_id":"USER01","message":"message-001"},{"order_id":"888888_2","address":"0xf16B7B8900F0d2f682e0FFe207a553F52B6C7015","amount":"0.0002","memo":"memo-002","user_id":"USER01","message":"message-002"}]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions

Cancel Withdrawal Request

curl -X POST http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/{ORDER_ID}/cancel

Query Latest Withdrawal Transaction State

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/{ORDER_ID}

Query All Withdrawal Transaction States

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/{ORDER_ID}/all

Query Withdrawal Transaction Event Logs

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/eventlog?txid={TXID}

Query Withdrawal Wallet Balance

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/balance

Query Withdrawal Callback Detail

curl 'http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/notifications/order_id/{ORDER_ID}'

Set Withdrawal Request ACL

curl -X POST -H "Content-Type: application/json" -d '{"acl":"192.168.101.55"}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/acl

Query Withdrawal Whitelist Configuration

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/whitelist/config

Query Withdrawal Wallet Transaction History

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions

Sign Message

curl -X POST -H "Content-Type: application/json" -d '{"message":"This is proof that I, user A, have access to this address."}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/signmessage

Call Contract Read ABI

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/contract/read?contract=0xad6d458402f60fd3bd25163575031acdce07538d&data=0xdd62ed3e000000000000000000000000d11bd6e308b8dc1c5243d54cf41a427ca0f46943000000000000000000000000e592427a0aece92de3edee1f18e0157c05861564

Arweave Sign Transaction

curl -X POST -H "Content-Type: application/json" -d '{"ar_tx":"{\"format\":2,\"id\":\"\",\"last_tx\":\"4z4iqqw4j_bBC1jXvm-pbMDg5eSYOGPjRz2fB1nsai6cVtvTd7Ucn-_Qau_bZh\",\"owner\":\"KkTVKjrry_aieBmqNOuUGtJam-3yT6zMABY89pinlcY\",\"tags\":[{\"name\":\"Q29udGVudC1UeXBl\",\"value\":\"aW1hZ2UvanBlZw\"}],\"target\":\"\",\"quantity\":\"0\",\"data\":\"\",\"data_size\":\"23782\",\"data_root\":\"Ve1yivS-iMklYK6xyPT58IeZRu-TtnAYkW5Ih4pb-S4\",\"reward\":\"73874553\",\"signature\":\"\",\"chunks\":\"\"}"}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/signtransaction

Add Withdrawal Whitelist Entry

curl -X POST -H "Content-Type: application/json" -d '{"items":[{"address":"GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ","memo":"85666","user_id":"USER002"}]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/whitelist

Remove Withdrawal Whitelist Entry

curl -X DELETE -H "Content-Type: application/json" -d '{"items":[{"address":"GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ","memo":"85666","user_id":"USER002"}]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/whitelist

Check Withdrawal Whitelist

curl -X POST -H "Content-Type: application/json" -d '{"address":"GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ","memo":"85666","user_id":"USER002"}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/whitelist/check

Query Withdrawal Whitelist

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/whitelist

Resend Withdrawal Callbacks

curl -X POST -H "Content-Type: application/json" -d '{"notification_id":0}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/notifications/manual

Query Callback History

curl 'http://localhost:8889/v1/mock/wallets/{WALLET_ID}/notifications?from_time=1561651200&to_time=1562255999&type=2'

Query Callback Detail

curl -X POST -H "Content-Type: application/json" -d '{"ids":[90000000140,90000000139]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/notifications/get_by_id

Query Wallet Synchronization Info

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/blocks

Query Transaction Average Fee

curl -X POST -H "Content-Type: application/json" -d '{"block_num":1}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/autofee

Batch Query Transaction Average Fees

curl -X POST -H "Content-Type: application/json" -d '{"block_nums":[1,5,10]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/autofees

Query Vault Wallet Transaction History

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/transactions?start_index=0&from_time=1559664000&to_time=1562255999&request_number=8

Query Vault Wallet Balance

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/vault/balance

Activate API Code

curl -X POST http://localhost:8889/v1/mock/wallets/{WALLET_ID}/apisecret/activate

Query API Code Status

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/apisecret

Refresh API Code

curl -X POST -H "Content-Type: application/json" -d '{"refresh_code":"3EbaSPUpKzHJ9wYgYZqy6W4g43NT365bm9vtTfYhMPra"}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/refreshsecret

Query Wallet Info

curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/info

Verify Addresses

curl -X POST -H "Content-Type: application/json" -d '{"addresses":["0x635B4764D1939DfAcD3a8014726159abC277BecC","1CK6KHY6MHgYvmRQ4PAafKYDrg1ejbH1cE"]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/verify

Inspect Callback Endpoint

curl -X POST -H "Content-Type: application/json" -d '{"test_number":102999}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/notifications/inspect

List Wallets

curl http://localhost:8889/v1/mock/wallets/readonly/walletlist

Query Wallets Balance

curl http://localhost:8889/v1/mock/wallets/readonly/walletlist/balances

Query Currency Prices

curl http://localhost:8889/v1/mock/currency/prices

Query Contract Token Meta

curl -X POST -H "Content-Type: application/json" -d '{"requests":[{"token_address":"0x9fceceda8a781e493a0eba6a59c6e6c731fd5ee5","token_id":"1"}]}' \
http://localhost:8889/v1/mock/currency/{CURRENCY}/contract/get-multiple-tokenuri

Query Service Health Status

curl http://localhost:8889/v1/mock/healthcheck
Back to top

Other Language Versions

Use Postman to evaluate

  • Import the API collection from Run in Postman
Back to top

Appendix

Callback Definition

Field Type Description
type int
IDType
1Deposit
2Withdraw
3Collect
4Airdrop
serial int The unique serial of callback
order_id string The unique order ID of withdrawal request
currency string Cryptocurrency of the callback
This field is for human reading only and may change in the future. Do not use this string as currency definition, use the fields currency_bip44 and token_address as currency definition.
txid string Transaction identifier
block_height int64 The block height show the transaction was packed in which block
tindex int The index of transaction in its block
vout_index int The index of vout in its transaction
amount string Transaction amount denominated in the smallest cryptocurrency unit
fees string Mining fee denominated in the smallest cryptocurrency unit
broadcast_at int64 When to broadcast the transaction in UTC time
chain_at int64 When was the transaction packed into block (in chain) in UTC time
from_address string The source address of the transaction
to_address string The destination address of the transaction
wallet_id int64 The wallet ID of the callback
state int Possible states (listed in the Transaction State Definition table)
IDDescription
1Processing
2TXID in pool
3TXID in chain
5Failed (the err_reason of addon field will contain detailed error reason).
* If the callback state is 5 with err_reason "nonce too low" after accelerating a pending transaction. This means that the pending transaction is already on the chain and awaiting the confirmation of the pending transaction. Don't need to accelerate again.
8Cancelled
10Dropped
11Transaction Failed
confirm_blocks int64 Number of confirmations
processing_state int
IDDescription
-1If the state is 5(failed), 8(cacelled), 10(dropped) or 11(transaction failed)
0In fullnode mempool
1In chain (the transaction is already on the blockchain but the confirmations have not been met)
2Done (the transaction is already on the blockchain and satisfy confirmations)
addon key-value pairs The extra information of this callback
KeyValue (Description)
err_reasonWill contain detail error reason if state is 5(Failed)
fee_decimalThe decimal of cryptocurrency miner fee
blocklist_tagsThe tags of CYBAVO AML detection
address_labelThe label of the deposit address
contract_abiThe contract ABI of the withdrawal request
token_idTransferred token ID
aml_tagsDetailed CYBAVO AML detection information includes score, tags and blocked flag
aml_screen_passPass or fail CYBAVO AML screening
decimal int The decimal of cryptocurrency
currency_bip44 int64 Refer to Currency Definition table
token_address string The contract address of cryptocurrency
memo string The memo/destination tag of the transaction

Transaction State Definition

ID State Description Callback Callback Type
0 Init The withdrawal request has been enqueued in the CYBAVO SOFA system - -
1 Processing The withdrawal request is processing in the CYBAVO SOFA system O Withdrawal(2)
2 TXID in pool The withdrawal transaction is pending in the fullnode mempool O Withdrawal(2)
3 TXID in chain The transaction is already on the blockchain O Deposit(1), Withdrawal(2), Collect(3)
4 TXID confirmed in N blocks The withdrawal transaction is already on the blockchain and satisfy confirmations - -
5 Failed Fail to create the withdrawal transaction O Withdrawal(2)
6 Resent The transaction has been successfully resent - -
7 Blocked due to risk controlled The deposit or withdrawal transaction was temporarily blocked due to a violation of the risk control rules - -
8 Cancelled The withdrawal request is cancelled via web console O Withdrawal(2)
9 UTXO temporarily not available The withdrawal request has been set as pending due to no available UTXO - -
10 Dropped A long-awaited withdrawal transaction that does not appear in the memory pool of the fullnode will be regarded as dropped O Withdrawal(2)
11 Transaction Failed The withdrawal transaction is regarded as a failed transaction by the fullnode O Withdrawal(2)
12 Paused The withdrawal request has been paused - -
13 Retrying Automatic transaction retry in progress - -
14 Query transaction status fail Unable to query transaction status from fullnode - -
15 Init-Locked Transaction is being processed in the KMS module - -
20 Preparing transaction fee Preparing transaction fee (delegated wallet only) - -
21 Transaction fee is ready Transaction fee is ready (delegated wallet only) - -

Callback sample:

If the state of callback is 5 (Failed), the detailed failure reason will put in addon field (key is err_reason). See the callback sample bellow.

{
  "type": 1,
  "serial": 90000000619,
  "order_id": "",
  "currency": "ETH",
  "txid": "0xc99a4941f87364c9679fe834f99bc12cbacfc577dedf4f34c4fd8833a68a0b00",
  "block_height": 8336269,
  "tindex": 43,
  "vout_index": 0,
  "amount": "500000000000000000",
  "fees": "945000000000000",
  "memo": "",
  "broadcast_at": 1595296751,
  "chain_at": 1595296751,
  "from_address": "0x8382Cc1B05649AfBe179e341179fa869C2A9862b",
  "to_address": "0x32d638773cB85965422b3B98e9312Fc9392307BC",
  "wallet_id": 5,
  "state": 3,
  "confirm_blocks": 2,
  "processing_state": 2,
  "addon": {
    "fee_decimal": 18
  },
  "decimal": 18,
  "currency_bip44": 60,
  "token_address": ""
}

Callback with state 5 (Failed) sample:

{
  "type": 2,
  "serial": 20000000155,
  "order_id": "1_69",
  "currency": "ETH",
  "txid": "",
  "block_height": 0,
  "tindex": 0,
  "vout_index": 0,
  "amount": "1000000000000000",
  "fees": "",
  "memo": "",
  "broadcast_at": 0,
  "chain_at": 0,
  "from_address": "",
  "to_address": "0x60589A749AAC632e9A830c8aBE041899d8Dd15",
  "wallet_id": 2,
  "state": 5,
  "confirm_blocks": 0,
  "processing_state": 0,
  "addon": {
    "err_reason": "Illegal Transaction Format: To 0x60589A749AAC632e9A830c8aBE041899d8Dd15"
  },
  "decimal": 18,
  "currency_bip44": 60,
  "token_address": ""
}

Deposit callback with blocklist_tags sample:

{
  "type": 1,
  "serial": 90000002797,
  "order_id": "",
  "currency": "ETH",
  "txid": "0xbb38e22c33cbc33ad5a58a88bfee0905968062fe34e33eb6e28861771686cf45",
  "block_height": 11075566,
  "tindex": 7,
  "vout_index": 0,
  "amount": "10000000000000000",
  "fees": "31500000315000",
  "memo": "",
  "broadcast_at": 1632195931,
  "chain_at": 1632195931,
  "from_address": "0xD5909BacFc1faD78e4e45E9e2feF8b4e61c8Fd0d",
  "to_address": "0x319b269ef02AB7e6660f7e6cb181D0CD06E2E4a0",
  "wallet_id": 854512,
  "processing_state": 2,
  "addon": {
    "address_label": "",
    "aml_screen_pass": false,
    "aml_tags": {
      "cybavo": {
        "score": 100,
        "tags": ["TEST"],
        "blocked": true
      }
    },
    "blocklist_tags": ["cybavo(100): TEST"],
    "fee_decimal": 18
  },
  "decimal": 18,
  "currency_bip44": 60,
  "token_address": ""
}
Back to top

Callback Type Definition

ID Description
1 Deposit Callback
2 Withdraw Callback
3 Collect Callback
4 Airdrop Callback
127 In-pool Transaction Callback
-1 All callbacks (for inquiry)
Back to top

Currency Definition

ID Currency Symbol Decimals
0 BTC 8
2 LTC 8
3 DOGE 8
5 DASH 8
60 ETH 18
118 ATOM 6
144 XRP 6
145 BCH (BCHN) 8
148 XLM 7
194 EOS 4
195 TRX 6
236 BSV 8
283 ALGO 6
354 DOT 10
434 KSM 12
461 FIL 18
472 AR 12
501 SOL 9
539 FLOW 8
700 XDAI 18
714 BNB 8
966 MATIC 18
1001 TT 18
1023 ONE 18
1729 XTZ 6
1776 L-BTC 8
1815 ADA 6
8217 KLAY 18
9001 ARBITRUM_BIP44 18
9005 AVAXC_BIP44 18
5353 HNS 6
52752 CELO 18
99999999976* ETH(Goerli) 18
99999999978* CRO 18
99999999979* NYM 6
99999999980* SOMM 18
99999999981* EVMOS 18
99999999982* AXL 6
99999999983* BLD 6
99999999984* OSMO 6
99999999986* KUB 18
99999999986* KUB 18
99999999987* KOVAN 18
99999999988* AVAX-C 18
99999999989* PALM 18
99999999990* FTM 18
99999999991* OKT 18
99999999992* OPTIMISM 18
99999999993* ARBITRUM 18
99999999994* HECO 18
99999999996* WND 12
99999999997* BSC 18

Refer to here for more detailed currency definitions

The * mark represents the definition of pseudo-cryptocurrency in the CYBAVO SOFA system

Back to top

Support Unconfirmed Balance Currency

ID Currency Symbol
0 BTC
2 LTC
3 DOGE
5 DASH
60 ETH
145 BCH (BCHN)
236 BSV
1776 L-BTC

And all EVM Compatible Currency

L-BTC only shows the unconfirmed incoming balance, no outgoing balance.

Back to top

Memo Requirement

Currency Description
XRP Up to 32-bit unsigned integer (max 4294967295)
XLM Up to 20 chars
EOS Up to 256 chars
BNB Up to 128 chars
ATOM Up to 180 chars
Back to top

Wallet Type Definition

Type Description
0 Vault wallet
1 Batch wallet
2 Deposit wallet
3 Withdrawal wallet
5 Deposit-withdrawal wallet
6 Delegated wallet
Back to top

Delegated Wallet Supported Currency

Same as EVM Compatible Currency

Back to top

EVM Compatible Currency

ID Currency Symbol
60 ETH
700 XDAI
966 MATIC
1001 TT
1023 ONE
9001 ARBITRUM_BIP44
9005 AVAXC_BIP44
52752 CELO
99999999976* ETH(Goerli)
99999999978* CRO
99999999986* KUB
99999999987* KOVAN
99999999988* AVAX-C
99999999989* PALM
99999999990* FTM
99999999991* OKT
99999999992* OPTIMISM
99999999993* ARBITRUM
99999999994* HECO
99999999997* BSC
Back to top

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.