How to withdraw assets

Steps to Withdraw Assets

To be able to withdraw assets from an account, the account must be open, the account must have disbursements-frozen set to false, and have disbursable assets of the asset being disbursed. Once these criteria have been met assets can be withdrawn from an account via asset-disbursements with an outgoing asset-transfer-method. The steps to make a disbursement out of an account is as follows.

  1. Create an outgoing asset-transfer-method of the desired asset and asset-transfer-type. This can also be created in line with the `asset-disbursement.

  2. Create an asset-disbursement with the asset-transfer-method.

Seen below is a withdrawal made with an outgoing asset-transfer-method for bitcoin.

Request

POST v2/asset-transfer-methods
{
"data" : {
"type" : "asset-transfer-methods",
"attributes" : {
"label" : "Personal Wallet Address",
"asset-id" : "798debbc-ec84-43ea-8096-13e2ebcf4749",
"contact-id" : "{{contact-id}}",
"account-id" :"{{account-id}}",
"wallet-address" : "mqtVQx2rtiQ98HyZ9aR8Aob3p69Pjoz7gf",
"transfer-direction" : "outgoing",
"single-use" : "false",
"asset-transfer-type" : "bitcoin"
}
}
}

Response

{
"data": {
"type": "asset-transfer-methods",
"id": "13d9f563-3da4-4fbf-b248-c75594035ec4",
"attributes": {
"acquisition-on": null,
"asset-transfer-type": "bitcoin",
"cost-basis": null,
"created-at": "2019-12-06T22:45:45Z",
"currency-type": null,
"label": "Personal Wallet Address",
"inactive": false,
"single-use": false,
"transfer-direction": "outgoing",
"wallet-address": "mqtVQx2rtiQ98HyZ9aR8Aob3p69Pjoz7gf"
},
"links": {
"self": "/v2/asset-transfer-methods/13d9f563-3da4-4fbf-b248-c75594035ec4"
},
"relationships": {
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"asset": {
"links": {
"related": "/v2/assets/798debbc-ec84-43ea-8096-13e2ebcf4749"
}
},
"asset-transfers": {
"links": {
"related": "/v2/asset-transfers?asset-transfer-method.id=13d9f563-3da4-4fbf-b248-c75594035ec4"
}
},
"contact": {
"links": {
"related": "/v2/contacts/7ae9525b-4127-48e8-a089-80199b0383cd"
}
}
}
},
"included": []
}

Make a withdrawal

Request

POST v2/asset-disbursements?include=asset-transfer-method,asset-transfer
{
"data" : {
"type" : "asset-disbursements",
"attributes" : {
"asset-id" : "{{btc-asset-id}}",
"asset-transfer" : {
"asset-transfer-method-id": "{{asset-transfer-method-outgoing-id}}"
},
"unit-count" : "10",
"account-id" : "{{account-id}}",
"contact-id" : "{{contact-id}}"
}
}
}

Response

{
"data": {
"type": "asset-disbursements",
"id": "1974d7ae-e748-4824-9054-8cac5a83187c",
"attributes": {
"unit-count": 10,
"created-at": "2019-12-06T22:53:55Z",
"updated-at": "2019-12-06T22:53:55Z"
},
"links": {
"self": "/v2/asset-disbursements/1974d7ae-e748-4824-9054-8cac5a83187c"
},
"relationships": {
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"asset": {
"links": {
"related": "/v2/assets/798debbc-ec84-43ea-8096-13e2ebcf4749"
}
},
"asset-transfer": {
"data": {
"type": "asset-transfers",
"id": "bf7f1dd7-47de-443b-8861-83f5d895f84b"
}
},
"asset-transfer-method": {
"data": {
"type": "asset-transfer-methods",
"id": "13d9f563-3da4-4fbf-b248-c75594035ec4"
}
},
"contact": {
"links": {
"related": "/v2/contacts?asset-transfers.id=bf7f1dd7-47de-443b-8861-83f5d895f84b&one"
}
},
"disbursement-authorization": {
"links": {
"related": "/v2/disbursement-authorizations?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b&one"
}
}
}
},
"included": [
{
"type": "asset-transfer-methods",
"id": "13d9f563-3da4-4fbf-b248-c75594035ec4",
"attributes": {
"acquisition-on": null,
"asset-transfer-type": "bitcoin",
"cost-basis": null,
"created-at": "2019-12-06T22:45:45Z",
"currency-type": null,
"label": "Personal Wallet Address",
"inactive": false,
"single-use": false,
"transfer-direction": "outgoing",
"wallet-address": "mqtVQx2rtiQ98HyZ9aR8Aob3p69Pjoz7gf"
},
"links": {
"self": "/v2/asset-transfer-methods/13d9f563-3da4-4fbf-b248-c75594035ec4"
},
"relationships": {
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"asset": {
"links": {
"related": "/v2/assets/798debbc-ec84-43ea-8096-13e2ebcf4749"
}
},
"asset-transfers": {
"links": {
"related": "/v2/asset-transfers?asset-transfer-method.id=13d9f563-3da4-4fbf-b248-c75594035ec4"
}
},
"contact": {
"links": {
"related": "/v2/contacts/7ae9525b-4127-48e8-a089-80199b0383cd"
}
}
}
},
{
"type": "asset-transfers",
"id": "bf7f1dd7-47de-443b-8861-83f5d895f84b",
"attributes": {
"cancelled-at": null,
"created-at": "2019-12-06T22:53:55Z",
"contingencies-cleared-on": null,
"status": "pending",
"unit-count": -10,
"unit-count-expected": -10,
"settlement-details": null
},
"links": {
"self": "/v2/asset-transfers/bf7f1dd7-47de-443b-8861-83f5d895f84b"
},
"relationships": {
"contingent-holds": {
"links": {
"related": "/v2/contingent-holds?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b"
}
},
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"asset": {
"links": {
"related": "/v2/assets/798debbc-ec84-43ea-8096-13e2ebcf4749"
}
},
"asset-contribution": {
"links": {
"related": "/v2/asset-contributions?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b&one"
}
},
"asset-disbursement": {
"links": {
"related": "/v2/asset-disbursements?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b&one"
}
},
"asset-transfer-method": {
"data": {
"type": "asset-transfer-methods",
"id": "13d9f563-3da4-4fbf-b248-c75594035ec4"
}
},
"contact": {
"links": {
"related": "/v2/contacts/7ae9525b-4127-48e8-a089-80199b0383cd"
}
},
"disbursement-authorization": {
"links": {
"related": "/v2/disbursement-authorizations?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b&one"
}
},
"settled-asset-transaction": {
"data": null
}
}
}
]
}

Track a withdrawal

The lifecycle of the asset-disbursement request should be tracked via the corresponding asset-transfer. An outgoing asset-transfer needs to be verified and authorized via the disbursement-authorization and all related contingent-holds also need to be cleared before the outgoing asset-transfer can be settled.

Request

GET v2/asset-transfers?include=disbursement-authorizations

Response

{
"links": {
"self": "/v2/asset-transfers?filter%5Bid+eq%5D=bf7f1dd7-47de-443b-8861-83f5d895f84b&include=disbursement-authorization",
"first": "/v2/asset-transfers?filter%5Bid+eq%5D=bf7f1dd7-47de-443b-8861-83f5d895f84b&include=disbursement-authorization&page%5Bnumber%5D=1&page%5Bsize%5D=25"
},
"meta": {
"page-count": 1,
"resource-count": 1
},
"data": [
{
"type": "asset-transfers",
"id": "bf7f1dd7-47de-443b-8861-83f5d895f84b",
"attributes": {
"cancelled-at": null,
"created-at": "2019-12-06T22:53:55Z",
"contingencies-cleared-on": null,
"status": "pending",
"unit-count": -10,
"unit-count-expected": -10,
"settlement-details": null
},
"links": {
"self": "/v2/asset-transfers/bf7f1dd7-47de-443b-8861-83f5d895f84b"
},
"relationships": {
"contingent-holds": {
"links": {
"related": "/v2/contingent-holds?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b"
}
},
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"asset": {
"links": {
"related": "/v2/assets/798debbc-ec84-43ea-8096-13e2ebcf4749"
}
},
"asset-contribution": {
"links": {
"related": "/v2/asset-contributions?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b&one"
}
},
"asset-disbursement": {
"links": {
"related": "/v2/asset-disbursements?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b&one"
}
},
"asset-transfer-method": {
"links": {
"related": "/v2/asset-transfer-methods/13d9f563-3da4-4fbf-b248-c75594035ec4"
}
},
"contact": {
"links": {
"related": "/v2/contacts/7ae9525b-4127-48e8-a089-80199b0383cd"
}
},
"disbursement-authorization": {
"data": {
"type": "disbursement-authorizations",
"id": "806e3504-282f-4e33-9040-f3524353e319"
}
},
"settled-asset-transaction": {
"data": null
}
}
}
],
"included": [
{
"type": "disbursement-authorizations",
"id": "806e3504-282f-4e33-9040-f3524353e319",
"attributes": {
"authorized-at": null,
"created-at": "2019-12-06T22:53:55Z",
"last-owner-verification-request-at": "2019-12-06T22:53:55Z",
"owner-verification-data": null,
"owner-verification-type": "email",
"owner-verified-at": null,
"status": "pending"
},
"links": {
"self": "/v2/disbursement-authorizations/806e3504-282f-4e33-9040-f3524353e319"
},
"relationships": {
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"disbursement": {
"data": null
},
"asset-disbursement": {
"links": {
"related": "/v2/asset-disbursements?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b&one"
}
},
"funds-transfer": {
"data": null
},
"asset-transfer": {
"links": {
"related": "/v2/asset-transfers/bf7f1dd7-47de-443b-8861-83f5d895f84b"
}
}
}
}
]
}

The disbursement-authorization is verified via a customizable email sent to the emails listed on contacts linked to the account with an account-role of owner. It can be cleared in sandbox as seen below. Generally authorization is automatic after the disbursement-authorization has been owner-verified but this depends on the account-policy, this can also be done in sandbox.

Request

POST v2/disbursement-authorizations/{{disbursement-authorization-asset-id}}/sandbox/verify-owner

Response

{
"data": {
"type": "disbursement-authorizations",
"id": "806e3504-282f-4e33-9040-f3524353e319",
"attributes": {
"authorized-at": "2019-12-06T23:26:07Z",
"created-at": "2019-12-06T22:53:55Z",
"last-owner-verification-request-at": "2019-12-06T22:53:55Z",
"owner-verification-data": {
"ip_address": "24.253.117.242",
"user_agent": "PostmanRuntime/7.19.0"
},
"owner-verification-type": "email",
"owner-verified-at": "2019-12-06T23:26:07Z",
"status": "authorized"
},
"links": {
"self": "/v2/disbursement-authorizations/806e3504-282f-4e33-9040-f3524353e319"
},
"relationships": {
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"disbursement": {
"data": null
},
"asset-disbursement": {
"links": {
"related": "/v2/asset-disbursements?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b&one"
}
},
"funds-transfer": {
"data": null
},
"asset-transfer": {
"links": {
"related": "/v2/asset-transfers/bf7f1dd7-47de-443b-8861-83f5d895f84b"
}
}
}
},
"included": []
}

Once the disbursement-authorization and the contingent-holds related to the outgoing asset-transfer are authorized and cleared respectively then the asset-transfer can be settled as seen below in sandbox. Once a asset-transfer settles a corresponding asset transaction will be created.

Request

POST v2/asset-transfers/{{asset-transfer-outgoing}}/sandbox/settle

Response

{
"data": {
"type": "asset-transfers",
"id": "bf7f1dd7-47de-443b-8861-83f5d895f84b",
"attributes": {
"cancelled-at": null,
"created-at": "2019-12-06T22:53:55Z",
"contingencies-cleared-on": "2019-12-06",
"status": "settled",
"unit-count": -10.0,
"unit-count-expected": -10.0,
"settlement-details": "Settled via sandbox API"
},
"links": {
"self": "/v2/asset-transfers/bf7f1dd7-47de-443b-8861-83f5d895f84b"
},
"relationships": {
"contingent-holds": {
"links": {
"related": "/v2/contingent-holds?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b"
}
},
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"asset": {
"links": {
"related": "/v2/assets/798debbc-ec84-43ea-8096-13e2ebcf4749"
}
},
"asset-contribution": {
"links": {
"related": "/v2/asset-contributions?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b&one"
}
},
"asset-disbursement": {
"links": {
"related": "/v2/asset-disbursements?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b&one"
}
},
"asset-transfer-method": {
"links": {
"related": "/v2/asset-transfer-methods/13d9f563-3da4-4fbf-b248-c75594035ec4"
}
},
"contact": {
"links": {
"related": "/v2/contacts/7ae9525b-4127-48e8-a089-80199b0383cd"
}
},
"disbursement-authorization": {
"links": {
"related": "/v2/disbursement-authorizations?asset-transfer.id=bf7f1dd7-47de-443b-8861-83f5d895f84b&one"
}
},
"settled-asset-transaction": {
"links": {
"related": "/v2/asset-transactions/54e0256f-0fc1-44f4-9d9e-546172082603"
}
}
}
},
"included": []
}

See also

  • Assets

  • Asset Transfer Methods

  • Asset Disbursements

  • Account Transfers

  • Asset Transactions

  • Account Asset Totals

  • Asset Transaction Tax Lots

  • Contingent-Holds

Last updated on