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

FieldTypeNoteDescription
order_idstringrequired, max 255 charsSpecify an unique ID, order ID must be prefixed
addressstringrequiredOutgoing address
amountstringrequiredWithdrawal amount
memostringoptionalMemo on blockchain (This memo will be sent to blockchain). Refer to [Memo Requirement]({{ ref “memo-requirement” >}})
user_idstringoptionalSpecify certain user
messagestringoptionalMessage (This message only savced on CYBAVO, not sent to blockchain)
block_average_feeintoptional, range 1~30Use average blockchain fee within latest N blocks
manual_feeintoptional, range 1~1000Specify blockchain fee in smallest unit of wallet currency
ignore_black_listbooleanoptional, default falseAfter setting, the address check will not be performed.

Response Body

FieldTypeDescription
resultsarrayArray 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:

FieldTypeDescription
error_codeintThe error code
errorstringThe error message
blacklistobjectThe object describes all problematic addresses and their causes.

Error Code

HTTP CodeError CodeErrorMessageDescription
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
400112Invalid parameter-Malformatted post body
400955There is no content in your withdrawal request, please check your input-The post body of request doesn’t conform the API request specification
400703Operation failedorder_id must start with {ORDERID_PREFIX}The prefix of order_id is incorrect
400703Operation failedorder_id: {ORDER_ID} - the character \ or / is prohibited{ORDER_ID} is invalid
400703Operation failedorder_id: {ORDER_ID} is invalid{ORDER_ID} is invalid
400703Operation failedorder_id: {ORDER_ID} - memo is requiredThe outgoing address of {ORDER_ID} needs memo specified
400703Operation failedorder_id: {ORDER_ID} - destination tag is requiredThe outgoing address of {ORDER_ID} needs destination tag specified
400703Operation failedorder_id: {ORDER_ID} - invalid block_average_feeThe block_average_fee is out of range
400703Operation failedorder_id: {ORDER_ID} - invalid manual_feeThe manual_fee is out of range
400399Duplicated entry: {ORDER_ID}-The {ORDER_ID} is duplicated
400945The max length of BNB memo is 256 chars-Reached the limit of the length of BNB memo
400946The max length of EOS memo is 128 chars-Reached the limit of the length of EOS memo
400947The max length of XRP destination tag is 20 chars-Reached the limit of the length of XRP destination tag
400948The max length of XLM memo is 20 chars-Reached the limit of the length of XLM memo
400818Destination Tag must be integer-Wrong XRP destination tag format
400944The max length of order id is 255 chars-Reached the limit of the length of order_id
400703Operation failedDetailed error messageFailed to connect to authentication callback URL
400703Operation failedHTTP resp failed {HTTP_CODE}, body: {RESPONSE_BODY}The authentication callback URL returned status code other than 200
403827Outgoing address in black list, abort transaction-Some outgoing addresses are blacklisted, examine the response ‘blacklist’ field for detailed information
404304Wallet ID invalid-The wallet is not allowed to perform this request
404312Policy not found-No active withdrawal policy found
404703Operation failedUnrecognized response: {RESPONSE_BODY}, ‘OK’ expectedThe 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