github.com/CYBAVO/SOFA_MOCK_SERVER
VIEW in front of the API definition.WALLET_ID set as readonly to activate a read-only API code.
/v1/sofa/wallets/readonly/apisecret/activateTo 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).
Refer to Callback Definition, Callback Type Definition for detailed definition.
Please refer to the code snippet on the github project to know how to validate the callback payload.
Best practice:
processing state(1) -> transaction in pool state(2) -> transaction in chain state(3) -> repeats state 3 until the confirmation count is met
transaction in chain state(3) -> repeats state 3 until the confirmation count is met
Refer to Transaction State Definition for all transaction states definition.
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_statealways be 0 (In fullnode mempool) andstatealways be 2 (TXID in pool).
decimal and fee_decimal(in the addon field) fields of callback data to convert the unit.A succuessful API response (status code 200) will contain an X-CHECKSUM header for integrity and security checks.
Please refer to the code snippet on the github project to know how to validate the API response.
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.
POST /v1/sofa/wallets/WALLET_ID/addresses
Deposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/107950/addresses
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:
| 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
memosmust equal tocountwhile 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
labelsto assign labels, the array length of the labels must equal tocount. The label will be automatically synced to the child wallet.
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.
| 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 |
Verify that these addresses belong to a deposit wallet.
VIEW POST /v1/sofa/wallets/WALLET_ID/receiver/addresses/verify
Deposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/98675/receiver/addresses/verify
{
"addresses": [
"0x46d4AD967F68253f61D45a044dC7dC7B13E5A4B3",
"0x107FF19Ea5fB7de78392e7AcC2A2C7eace891bDc"
]
}
The request includes the following parameters:
| 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.
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) |
| 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 |
Query the deposit addresses created by the Create Deposit Addresses API.
VIEW GET /v1/sofa/wallets/WALLET_ID/addresses?start_index=from&request_number=count
Deposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/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 |
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.
| 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 |
Query deployed contract deposit addresses created by the Create Deposit Addresses API.
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.
An example of the request:
/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 |
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 |
| 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 |
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.
VIEW GET /v1/sofa/wallets/WALLET_ID/pooladdress
Deposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/179654/pooladdress
An example of a successful response:
{
"address": "0x36099775afa8d6363aC8e5d0fC698306C021a858"
}
The response includes the following parameters:
| Field | Type | Description |
|---|---|---|
| address | string | Pool address of wallet |
| 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 |
Get the pool address balance of a deposit wallet.
VIEW GET /v1/sofa/wallets/WALLET_ID/pooladdress/balance
Deposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/179654/pooladdress/balance
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 |
| 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 |
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.
VIEW GET /v1/sofa/wallets/WALLET_ID/addresses/invalid-deposit
Deposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/179654/addresses/invalid-deposit
An example of a successful response:
{
"addresses": ["0x5dB3d8C70dAa9C919F9962221c2fDDbe8EBAa5F2"]
}
The response includes the following parameters:
| Field | Type | Description |
|---|---|---|
| addresses | array | Array of invalid deposit address |
| 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 |
Query the detailed information of the deposit callback by the tx ID and the vout index.
VIEW GET /v1/sofa/wallets/WALLET_ID/receiver/notifications/txid/TX_ID/VOUT_INDEX
Deposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/179654/receiver/notifications/txid/0xb72a81976f780445decd13a35c24974c4e32665cb57d79b3f7a601c775f6a7d8/0
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 |
| 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 |
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.
POST /v1/sofa/wallets/WALLET_ID/collection/notifications/manual
Deposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/179654/collection/notifications/manual
{
"notification_id": 0
}
The request includes the following parameters:
| 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.
An example of a successful response:
{
"count": 0
}
The response includes the following parameters:
| Field | Type | Description |
|---|---|---|
| count | int | Count of callbacks just resent |
| 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 |
Get the deposit wallet balance.
VIEW GET /v1/sofa/wallets/WALLET_ID/receiver/balance
Deposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/959272/receiver/balance
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 |
| 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 |
Update the label of the deposit address.
POST /v1/sofa/wallets/WALLET_ID/addresses/label
Deposit WalletDeposit-withdrawal WalletDelegated WalletThe label will be automatically synced between the parent and child wallet.
An example of the request:
/v1/sofa/wallets/98675/addresses/label
{
"address": "0x2B974a3De0b491bB26e0bF146E6cDaC36EFD574a",
"label": "take-some-notes"
}
The request includes the following parameters:
| 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 |
Status code 200 represnts a successful operation
| 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 |
Query the labels of the deposit addresses.
VIEW POST /v1/sofa/wallets/WALLET_ID/addresses/get_labels
Deposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/98675/addresses/get_labels
{
"addresses": [
"0x2B974a3De0b491bB26e0bF146E6cDaC36EFD574a",
"0xF401AC94D9672e79c68e56A6f822b666E5A7d644"
]
}
The request includes the following parameters:
| Field | Type | Note | Description |
|---|---|---|---|
| addresses | array | required | Specify the addresses to query labels |
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.
| 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 |
Query the balace of delegated addresses.
VIEW POST /v1/sofa/wallets/WALLET_ID/receiver/get-balances
Delegated Wallet
An example of the request:
/v1/sofa/wallets/708453/receiver/get-balances
{
"addresses": [
"0x6A2969E4496d5b27967a68b411D7e0218943c1B6",
"0x1EA22Ed0347E6C9f852cfcBEFE752A026450164b",
"0x2baB9B3af6041960322a248d5315850fc79a3881"
]
}
The request includes the following parameters:
| 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.
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 |
| 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 |
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.
POST /v1/sofa/wallets/WALLET_ID/sender/transactions
Withdrawal WalletDeposit-withdrawal WalletDelegated WalletThe 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.
An example of the request:
The prefix is 888888_ in following sample request.
/v1/sofa/wallets/68451/sender/transactions
{
"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:
| 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_abiisABI_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_abito call ABI on smart contracts.Only ERC721/1155 token wallet can use
token_idto transfer token. For ERC721 wallets, iftoken_idis specified, the amount will be treated as 1.The
block_average_feeandmanual_feedo not work for XRP, XLM, BNB, DOGE, EOS, TRX, ADA, DOT and SOL cryptocurrencies.
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. |
| 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 |
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 ).
POST /v1/sofa/wallets/WALLET_ID/sender/transactions/ORDER_ID/cancel
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
The prefix is 888888_ in following sample request.
/v1/sofa/wallets/68451/sender/transactions/88888_1/cancel
The HTTP 200 means the withdrawal request has been cancelled successfully.
| 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 |
Check the latest withdrawal transaction state of certain order ID.
The order ID is used in the withdraw assets API.
VIEW GET /v1/sofa/wallets/WALLET_ID/sender/transactions/ORDER_ID
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
The prefix is 888888_ in following sample request.
/v1/sofa/wallets/68451/sender/transactions/888888_1
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 |
| 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 |
Check the all withdrawal transaction states of certain order ID.
The order ID is used in the withdraw assets API.
VIEW GET /v1/sofa/wallets/WALLET_ID/sender/transactions/ORDER_ID/all
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
The prefix is 888888_ in following sample request.
/v1/sofa/wallets/68451/sender/transactions/888888_1/all
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 |
| 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 |
Query event logs of a withdrawal transaction by transaction hash. Only EVM Compatible Currencies are supported.
VIEW GET /v1/sofa/wallets/WALLET_ID/sender/transactions/eventlog?txid=TXID
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/345312/sender/transactions/eventlog?txid=0xe82f0be9b30d840eca64e28e6f7562b7352b3b54519a7e63fb8f6d4609194bb9
The request includes the following parameters:
| Field | Type | Note | Description |
|---|---|---|---|
| txid | string | required | Representing the transaction hash to query the event log |
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 |
| 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 |
Get the withdrawal wallet balance. Facilitate to establish a real-time balance monitoring mechanism.
VIEW GET /v1/sofa/wallets/WALLET_ID/sender/balance
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/632543/sender/balance
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
| 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 |
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.
VIEW GET /v1/sofa/wallets/WALLET_ID/sender/notifications/order_id/ORDER_ID
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
The prefix is 888888_ in following sample request.
/v1/sofa/wallets/68451/sender/notifications/order_id/888888_1
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 |
| 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 |
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.
POST /v1/sofa/wallets/WALLET_ID/sender/transactions/acl
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/632543/sender/transactions/acl
{
"acl": "192.168.101.55"
}
The request includes the following parameters:
| Field | Type | Note | Description |
|---|---|---|---|
| acl | string | requried | Specify an authorized IP in IPv4 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 |
| 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 |
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.
POST /v1/sofa/wallets/WALLET_ID/sender/notifications/manual
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/55743/sender/notifications/manual
{
"notification_id": 0
}
The request includes the following parameters:
| 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.
An example of a successful response:
{
"count": 3
}
The response includes the following parameters:
| Field | Type | Description |
|---|---|---|
| count | int | Count of callbacks just resent |
| 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 |
Query the whitelist configuration of the withdrawal wallet.
VIEW GET /v1/sofa/wallets/WALLET_ID/sender/whitelist/config
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/55743/sender/whitelist/config
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. |
| 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 |
Add an outgoing address to the withdrawal wallet's whitelist.
POST /v1/sofa/wallets/WALLET_ID/sender/whitelist
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/55743/sender/whitelist
{
"items": [
{
"address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
"memo": "865314",
"user_id": "USER001"
}
]
}
The request includes the following parameters:
| 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 |
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 |
| 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 |
Remove an outgoing address from the withdrawal wallet's whitelist.
DELETE /v1/sofa/wallets/WALLET_ID/sender/whitelist
WALLET_IDmust be a withdrawal wallet ID
Only the entries exactly matches all the fields will be removed.
An example of the request:
/v1/sofa/wallets/55743/sender/whitelist
{
"items": [
{
"address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
"memo": "865314",
"user_id": "USER001"
}
]
}
The request includes the following parameters:
| 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 |
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 |
| 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 |
Check the withdrawal whitelist entry status in the withdrawal whitelist.
VIEW POST /v1/sofa/wallets/WALLET_ID/sender/whitelist/check
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/557432/sender/whitelist/check
{
"address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
"memo": "865314",
"user_id": "USER001"
}
The request includes the following parameters:
| 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 |
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 |
| 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 |
Used to query some kind of callbacks within a time interval.
VIEW GET /v1/sofa/wallets/WALLET_ID/sender/whitelist?from_time=from&to_time=to&start_index=offset&request_number=count&state=state
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/557432/sender/whitelist
The request includes the following 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 |
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 |
| 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 |
Get transaction history of withdrawal wallets.
VIEW GET /v1/sofa/wallets/WALLET_ID/sender/transactions?from_time=from&to_time=to&start_index=start&request_number=count
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/345312/sender/transactions?from_time=1559664000&to_time=1562255999&start_index=0&request_number=10
The request includes the following 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 |
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 |
| 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 |
| 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 |
Sign message, equivalent to eth_sign.
POST /v1/sofa/wallets/WALLET_ID/signmessage
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/557432/signmessage
{
"message": "This is proof that I, user A, have access to this address."
}
The request includes the following parameters:
| 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 |
An example of a successful response:
{
"signed_message": "0xf296a678ce1d577acbee25119b7be821db70e960d6e65ef73fb1e50fa832759d27d35df2dd309be07cb5a9b9f6c87f5eeae11ff56b995e0b32d6288b1039555b2a"
}
The response includes the following parameters:
| Field | Type | Description |
|---|---|---|
| signed_message | string | Signed message |
| 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 | - |
Executes a contract read ABI call.
VIEW GET /v1/sofa/wallets/WALLET_ID/contract/read?contract=contract_address&data=data
Withdrawal WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/345312/contract/read?contract=0xad6d458402f60fd3bd25163575031acdce07538d&data=0xdd62ed3e000000000000000000000000d11bd6e308b8dc1c5243d54cf41a427ca0f46943000000000000000000000000e592427a0aece92de3edee1f18e0157c05861564
The request includes the following 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
datamust be encoded by web3.eth.abi.encodeFunctionCall() of web3.js.
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
outputcan be decoded by web3.eth.abi.decodeparameters() of web3.js.
| 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 |
Sign Arweave transaction for uploading data. This API is dedicated to the Arweave withdrawal wallet.
POST /v1/sofa/wallets/WALLET_ID/signtransaction
Withdrawal Wallet
An example of the request:
/v1/sofa/wallets/557432/signtransaction
{
"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:
| 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.
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 |
| 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 |
Used to query some kind of callbacks within a time interval.
VIEW GET /v1/sofa/wallets/WALLET_ID/notifications?from_time=from&to_time=to&type=type
Withdrawal WalletDeposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/677414/notifications?from_time=1561651200&to_time=1562255999&type=2
The request includes the following 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 |
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 |
| 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 |
Query the detailed information of the callback by its serial ID. It can be used to reconfirm whether a deposit callback exists.
VIEW POST /v1/sofa/wallets/WALLET_ID/notifications/get_by_id
Withdrawal WalletDeposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/677414/notifications/get_by_id
{
"ids": [90000000140, 90000000139]
}
The request includes the following parameters:
| Field | Type | Note | Description |
|---|---|---|---|
| ids | array | requried | Specify the IDs for query |
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 |
| 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 |
Get the blockchain synchronization status of a wallet.
VIEW GET /v1/sofa/wallets/WALLET_ID/blocks
Withdrawal WalletDeposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/677414/blocks
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 |
| 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 |
Query average blockchain fee within latest N blocks.
VIEW POST /v1/sofa/wallets/WALLET_ID/autofee
Withdrawal WalletDeposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/635718/autofee
{
"block_num": 1
}
The request includes the following parameters:
| Field | Type | Note | Description |
|---|---|---|---|
| block_num | int | optional, default 1, range 1~100 | Query the average blockchain fee in the last N blocks |
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 |
| 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 |
Batch Query average blockchain fee within latest N blocks.
VIEW POST /v1/sofa/wallets/WALLET_ID/autofees
Withdrawal WalletDeposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/854714/autofees
{
"block_nums": [1, 5, 10]
}
The request includes the following parameters:
| 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 |
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 |
| 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 |
Get transaction history of vault wallets.
VIEW GET /v1/sofa/wallets/WALLET_ID/transactions?from_time=from&to_time=to&start_index=start&request_number=count&state=state
Vault Wallet
An example of the request:
/v1/sofa/wallets/488471/transactions?from_time=1559664000&to_time=1562255999&start_index=0&request_number=1
The request includes the following 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 |
| ID | Description |
|---|---|
| 0 | WaitApproval |
| 1 | Rejected |
| 2 | Approved |
| 3 | Failed |
| 4 | NextLevel |
| 5 | Cancelled |
| 6 | BatchDone |
| -1 | All states (for inquiry) |
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
| 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 |
Get the vault wallet balance. Facilitate to establish a real-time balance monitoring mechanism.
VIEW GET /v1/sofa/wallets/WALLET_ID/vault/balance
Vault Wallet
An example of the request:
/v1/sofa/wallets/488471/vault/balance
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
| 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 |
Activate the API code of a certain wallet. Once activated, the currently activated API code will immediately become invalid.
POST /v1/sofa/wallets/WALLET_ID/apisecret/activate
Withdrawal WalletDeposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/488471/apisecret/activate
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 |
| 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 |
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.
VIEW GET /v1/sofa/wallets/WALLET_ID/apisecret
Withdrawal WalletDeposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/488471/apisecret
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.
| 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 |
Use paired refresh code to acquire the new inactive API code/secret of the wallet.
POST /v1/sofa/wallets/WALLET_ID/refreshsecret
Withdrawal WalletDeposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/357818/refreshsecret
{
"refresh_code": "3EbaSPUpKzHJ9wYgYZqy6W4g43NT365bm9vtTfYhMPra"
}
The request includes the following parameters:
| Field | Type | Note | Description |
|---|---|---|---|
| refresh_code | string | required | The corresponding refresh code of the API code specified in the X-API-CODE header |
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 |
| 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 |
Get wallet basic information.
VIEW GET /v1/sofa/wallets/WALLET_ID/info
Withdrawal WalletDeposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/488471/info
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 |
| 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 |
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_memoflag to indicate whether the address needs a memo / destination tag when transferring cryptocurrency to that address.
VIEW POST /v1/sofa/wallets/WALLET_ID/addresses/verify
Wallet ID must be a deposit or withdraw wallet's ID
An example of the request:
/v1/sofa/wallets/488471/addresses/verify
{
"addresses": [
"0x635B4764D1939DfAcD3a8014726159abC277BecC",
"1CK6KHY6MHgYvmRQ4PAafKYDrg1ejbH1cE"
]
}
The request includes the following parameters:
| Field | Type | Note | Description |
|---|---|---|---|
| addresses | array | requried | Specify the address for verification |
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 |
| 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 |
Use to inspect the notification and withdrawal authentication endpoint.
VIEW POST /v1/sofa/wallets/WALLET_ID/notifications/inspect
Withdrawal WalletDeposit WalletDeposit-withdrawal WalletDelegated Wallet
An example of the request:
/v1/sofa/wallets/896541/notifications/inspect
{
"test_number": 102999
}
The request includes the following parameters:
| 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}. |
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 |
| 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 |
List all wallets can be accessed by the inquiry read-only API code.
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.
An example of the request:
/v1/sofa/wallets/readonly/walletlist
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 |
| 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 |
Query balance of all wallets can be accessed by the inquiry read-only API code.
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.
An example of the request:
/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 |
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_balancesinformation.
| 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 |
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.
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.
An example of the request:
/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.
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) |
| 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 |
Used to query token meta information for a specific contract.
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.
An example of the request:
/v1/sofa/currency/60/contract/get-multiple-tokenuri
{
"requests": [
{
"token_address": "0x9fceceda8a781e493a0eba6a59c6e6c731fd5ee5",
"token_id": "1"
}
]
}
The request includes the following parameters:
| 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 |
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. |
| 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 |
Used to query service health status.
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.
An example of the request:
/v1/sofa/healthcheck
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 |
| 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 |
Configure CYBAVO API server URL in mockserver.app.conf
api_server_url="BACKEND_SERVER_URL"
Put API code/secret to mock server's database
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
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
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
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses?start_index=0&request_number=1000
curl 'http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/contract_txid?txids={TXID1},{TXID2}'
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/pooladdress
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/pooladdress/balance
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/invalid-deposit
curl 'http://localhost:8889/v1/mock/wallets/{WALLET_ID}/receiver/notifications/txid/{TX_ID}/{VOUT_INDEX}'
curl -X POST -H "Content-Type: application/json" -d '{"notification_id":0}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/collection/notifications/manual
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/receiver/balance
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
curl -X POST -H "Content-Type: application/json" -d '{"addresses":["0x2B974a3De0b491bB26e0bF146E6cDaC36EFD574a","0xF401AC94D9672e79c68e56A6f822b666E5A7d644"]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/get_labels
curl -X POST -H "Content-Type: application/json" -d '{"addresses":["0x6A2969E4496d5b27967a68b411D7e0218943c1B6","0x1EA22Ed0347E6C9f852cfcBEFE752A026450164b","0x2baB9B3af6041960322a248d5315850fc79a3881"]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/receiver/get-balances
curl -X POST -H "Content-Type: application/json" -d '{"addresses":["0x46d4AD967F68253f61D45a044dC7dC7B13E5A4B3","0x107FF19Ea5fB7de78392e7AcC2A2C7eace891bDc"]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/receiver/addresses/verify
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
curl -X POST http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/{ORDER_ID}/cancel
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/{ORDER_ID}
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/{ORDER_ID}/all
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/eventlog?txid={TXID}
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/balance
curl 'http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/notifications/order_id/{ORDER_ID}'
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
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/whitelist/config
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions
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
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/contract/read?contract=0xad6d458402f60fd3bd25163575031acdce07538d&data=0xdd62ed3e000000000000000000000000d11bd6e308b8dc1c5243d54cf41a427ca0f46943000000000000000000000000e592427a0aece92de3edee1f18e0157c05861564
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
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
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
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
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/whitelist
curl -X POST -H "Content-Type: application/json" -d '{"notification_id":0}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/notifications/manual
curl 'http://localhost:8889/v1/mock/wallets/{WALLET_ID}/notifications?from_time=1561651200&to_time=1562255999&type=2'
curl -X POST -H "Content-Type: application/json" -d '{"ids":[90000000140,90000000139]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/notifications/get_by_id
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/blocks
curl -X POST -H "Content-Type: application/json" -d '{"block_num":1}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/autofee
curl -X POST -H "Content-Type: application/json" -d '{"block_nums":[1,5,10]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/autofees
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/transactions?start_index=0&from_time=1559664000&to_time=1562255999&request_number=8
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/vault/balance
curl -X POST http://localhost:8889/v1/mock/wallets/{WALLET_ID}/apisecret/activate
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/apisecret
curl -X POST -H "Content-Type: application/json" -d '{"refresh_code":"3EbaSPUpKzHJ9wYgYZqy6W4g43NT365bm9vtTfYhMPra"}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/refreshsecret
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/info
curl -X POST -H "Content-Type: application/json" -d '{"addresses":["0x635B4764D1939DfAcD3a8014726159abC277BecC","1CK6KHY6MHgYvmRQ4PAafKYDrg1ejbH1cE"]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/verify
curl -X POST -H "Content-Type: application/json" -d '{"test_number":102999}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/notifications/inspect
curl http://localhost:8889/v1/mock/wallets/readonly/walletlist
curl http://localhost:8889/v1/mock/wallets/readonly/walletlist/balances
curl http://localhost:8889/v1/mock/currency/prices
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
curl http://localhost:8889/v1/mock/healthcheck
| Field | Type | Description | ||||||||||||||||||
| type | int |
| ||||||||||||||||||
| 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)
| ||||||||||||||||||
| confirm_blocks | int64 | Number of confirmations | ||||||||||||||||||
| processing_state | int |
| ||||||||||||||||||
| addon | key-value pairs |
The extra information of this callback
| ||||||||||||||||||
| 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 |
| 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
stateof callback is 5 (Failed), the detailed failure reason will put inaddonfield (key iserr_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": ""
}
| ID | Description |
|---|---|
| 1 | Deposit Callback |
| 2 | Withdraw Callback |
| 3 | Collect Callback |
| 4 | Airdrop Callback |
| 127 | In-pool Transaction Callback |
| -1 | All callbacks (for inquiry) |
| 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 |
| 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
| 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.
| 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 |
| Type | Description |
|---|---|
| 0 | Vault wallet |
| 1 | Batch wallet |
| 2 | Deposit wallet |
| 3 | Withdrawal wallet |
| 5 | Deposit-withdrawal wallet |
| 6 | Delegated wallet |
Same as 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 |
FAQs
Unknown package
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.