Withdraw Assets

Withdraw assets from a withdrawal wallet.

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.

Request

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

Post Body

Field Type Note Description
order_id string required, max 255 chars Specify an unique ID, order ID must be prefixed
address string required Outgoing address
amount string required Withdrawal amount
memo string optional Memo on blockchain (This memo will be sent to blockchain). Refer to [Memo Requirement]({{ ref “memo-requirement” >}})
user_id string optional Specify certain user
message string optional Message (This message only savced on CYBAVO, not sent to blockchain)
block_average_fee int optional, range 1~30 Use average blockchain fee within latest N blocks
manual_fee int optional, range 1~1000 Specify blockchain fee in smallest unit of wallet currency
ignore_black_list boolean optional, default false After setting, the address check will not be performed.

Response Body

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

An example response of the request contains problematic addresses:

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

The response includes the following parameters:

Field Type Description
error_code int The error code
error string The error message
blacklist object The object describes all problematic addresses and their causes.

Error Code

HTTP Code Error Code Error Message Description
403 - Forbidden. Invalid wallet 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
400 112 Invalid parameter - Malformatted post body
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 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 HTTP resp failed {HTTP_CODE}, body: {RESPONSE_BODY} The authentication callback URL returned status code other than 200
403 827 Outgoing address in black list, abort transaction - Some outgoing addresses are blacklisted, examine the response ‘blacklist’ field for detailed information
404 304 Wallet ID invalid - The wallet is not allowed to perform this request
404 312 Policy not found - No active withdrawal policy found
404 703 Operation failed Unrecognized response: {RESPONSE_BODY}, ‘OK’ expected The withdrawal request is not allowed by authentication callback URL

Sample Request

API

/v1/sofa/wallets/94533/sender/transactions

Post Body

{
  "requests": [
    {
      "order_id": "888888_1",
      "address": "0x60589A749AAC632e9A830c8aBE042D1899d8Dd15",
      "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",
      "memo": "memo-002",
      "user_id": "USER02",
      "message": "message-002",
      "manual_fee": 50
    },
    {
      "order_id": "888888_3",
      "address": "0x9638fa816ccd35389a9a98a997ee08b5321f3eb9",
      "amount": "0.0002",
      "memo": "memo-003",
      "user_id": "USER03",
      "message": "message-003"
    }
  ],
  "ignore_black_list": false
}

Response Body

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

Sample cURL Command

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