Table of contents

• Get Started
• API Authentication
• Callback Integration
• Callback State Change
• In-pool Transaction Callback
• Cryptocurrency Unit Conversion
• API Response Validation
• REST API
  • Deposit API
    • Create Deposit Addresses
    • Verify Deposit Addresses
    • Query Deposit Addresses
    • Query Deployed Contract Deposit Addresses
    • Query Pool Address
    • Query Pool Address Balance
    • Query Invalid Deposit Addresses
    • Query Deposit Callback Detail
    • Resend Deposit/Collection Callbacks
    • Query Deposit Wallet Balance
    • Update Deposit Address Label
    • Query Deposit Address Label
    • Query Delegated Address Balance
  • Withdrawal API
    • Withdraw Assets
    • Cancel Withdrawal Request
    • Query Latest Withdrawal Transaction State
    • Query All Withdrawal Transaction States
    • Query Withdrawal Transaction Event Logs
    • Query Withdrawal Wallet Balance
    • Query Withdrawal Callback Detail
    • Set Withdrawal Request ACL
    • Resend Withdrawal Callbacks
    • Query Withdrawal Whitelist Configuration
    • Add Withdrawal Whitelist Entry
    • Remove Withdrawal Whitelist Entry
    • Check Withdrawal Whitelist
    • Query Withdrawal Whitelist
    • Query Withdrawal Wallet Transaction History
    • Sign Message
    • Call Contract Read ABI
    • Arweave Sign Transaction
  • Deposit / Withdraw Common API
    • Query Callback History
    • Query Callback Detail
    • Query Wallet Synchronization Info
    • Query Transaction Average Fee
    • Batch Query Transaction Average Fees
  • Vault API
    • Query Vault Wallet Transaction History
    • Query Vault Wallet Balance
  • Common API
    • Activate API Code
    • Query API Code Status
    • Refresh API Code
    • Query Wallet Info
    • Verify Addresses
    • Inspect Callback Endpoint
  • Read-only API code API
    • List Wallets
    • Query Wallets Balance
    • Query Currency Prices
    • Query Contract Token Meta
    • Query Service Health Status
• Testing
  • Mock Server
  • cURL Testing Commands
  • Other Language Versions
  • Use Postman to evaluate
• Appendix
  • Callback Definition
  • Transaction State Definition
  • Callback Type Definition
  • Currency Definition
  • Support Unconfirmed Balance Currency
  • Memo Requirement
  • Wallet Type Definition
  • Delegated Wallet Supported Currency
  • EVM Compatible Currency

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)
  • Refer to Create deposit addresses 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

• Use mock server to test CYBAVO SOFA API right away.

Start integration

• To make a correct API call, refer to API Authentication.
• To handle callback correctly, refer to Callback 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.
  • Go
  • Java
  • Javascript
  • PHP
  • C#
  • Python

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.
  • Use the activation API to activate an API code.
• 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.

  • Go
  • Java
  • Javascript
  • PHP
  • C#
  • Python

• 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.

  • Go
  • Java
  • Javascript
  • PHP

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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.

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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.

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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.

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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.

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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

• Sample curl command

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.

• Sample curl command

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.

• Sample curl command

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.

• Sample curl command

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.

• Sample curl command

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.

• Sample curl command

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

• API definition

Query Deposit Addresses

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

• API definition

Query Deployed Contract Deposit Addresses

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

• API definition

Query Pool Address

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

• API definition

Query Pool Address Balance

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

• API definition

Query Invalid Deposit Addresses

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

• API definition

Query Deposit Callback Detail

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

• API definition

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

• API definition

Query Deposit Wallet Balance

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

• API definition

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

• API definition

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

• API definition

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

• API definition

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

• API definition

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

• API definition

Cancel Withdrawal Request

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

• API definition

Query Latest Withdrawal Transaction State

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

• API definition

Query All Withdrawal Transaction States

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

• API definition

Query Withdrawal Transaction Event Logs

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

• API definition

Query Withdrawal Wallet Balance

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

• API definition

Query Withdrawal Callback Detail

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

• API definition

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

• API definition

Query Withdrawal Whitelist Configuration

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

• API definition

Query Withdrawal Wallet Transaction History

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

• API definition

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

• API definition

Call Contract Read ABI

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

• API definition

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

• API definition

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

• API definition

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

• API definition

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

• API definition

Query Withdrawal Whitelist

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

• API definition

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

• API definition

Query Callback History

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

• API definition

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

• API definition

Query Wallet Synchronization Info

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

• API definition

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

• API definition

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

• API definition

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

• API definition

Query Vault Wallet Balance

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

• API definition

Activate API Code

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

• API definition

Query API Code Status

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

• API definition

Refresh API Code

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

• API definition

Query Wallet Info

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

• API definition

Verify Addresses

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

• API definition

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

• API definition

List Wallets

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

• API definition

Query Wallets Balance

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

• API definition

Query Currency Prices

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

• API definition

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

• API definition

Query Service Health Status

curl http://localhost:8889/v1/mock/healthcheck

• API definition

Back to top

Other Language Versions

• Java
• Javascript
• PHP

Use Postman to evaluate

• Import the API collection from

Back to top

Appendix

Callback Definition

Field	Type	Description
type	int	ID Type 1 Deposit 2 Withdraw 3 Collect 4 Airdrop
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) ID Description 1 Processing 2 TXID in pool 3 TXID in chain 5 Failed (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. 8 Cancelled 10 Dropped 11 Transaction Failed
confirm_blocks	int64	Number of confirmations
processing_state	int	ID Description -1 If the state is 5(failed), 8(cacelled), 10(dropped) or 11(transaction failed) 0 In fullnode mempool 1 In chain (the transaction is already on the blockchain but the confirmations have not been met) 2 Done (the transaction is already on the blockchain and satisfy confirmations)
addon	key-value pairs	The extra information of this callback Key Value (Description) err_reason Will contain detail error reason if state is 5(Failed) fee_decimal The decimal of cryptocurrency miner fee blocklist_tags The tags of CYBAVO AML detection address_label The label of the deposit address contract_abi The contract ABI of the withdrawal request token_id Transferred token ID aml_tags Detailed CYBAVO AML detection information includes score, tags and blocked flag aml_screen_pass Pass 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