Transfer methods

Filtering by object parameters can be applied according to the JSON API Specification.

Transfer object

Name	Type	Description
`id`	string	The unique system identifier of a transfer. This value is generated automatically at the moment of transfer creation and can’t be changed.
`op_id`	number	For deposits and payouts, this is the unique operation identifier in the system.
`op_type`	number	The transfer purpose. For possible values, refer to Transfer types.
`amount`	string	The transfer amount, in the payment currency, excluding fees and commissions.
`rate_target`	string	If the payment currency differs from the wallet currency, this is the exchange rate of the payment currency to the wallet currency, valid at the moment of transaction execution. If the payment currency is the same as the wallet currency, this value is equal to `1`.
`commission`	string	The fee charged by Coinsbuy for transaction processing, in the payment currency.
`fee`	string	The blockchain fee charged for processing an on-chain transaction, in the payment currency.
`txid`	string	The blockchain transaction identifier, the same as the transaction hash.
`status`	number	The current status of a transfer. Possible values: `-3` — Canceled — the transfer was canceled due to security reasons or a transfer amount being too small. `-2` — Blocked — the transfer was considered suspicious during the AML check and is temporarily blocked until further Compliance verification. `-1` — Failed — the transfer has failed on the blockchain. `0` — Created — the transfer has been created and is currently in the queue for processing, the status will be changed soon. `1` — Unconfirmed — the transfer hasn’t yet received the required number of block confirmations. `2` — Confirmed — the required number of block confirmations has been received and the transfer is completed.
`user_message`	string or null	Any comment for an operation made via the Coinsbuy Back Office.
`created_at`	string	The date and time when a transfer was created.
`updated_at`	string	The date and time when a transfer status was last updated.
`confirmations`	number	The current number of received confirmations on the blockchain.
`risk`	number	The AML risk percentage for a transfer. Possible range of values is from `0` to `100`, where `100` is the highest risk. May be `null` if AML verification hasn’t been performed.
`risk_status`	number	The status of AML verification of a transfer. Possible values: `1` — Checked — the transfer has successfully passed the AML check. `2` — Pending — the AML check is in progress. `3` — Failed — the AML check has failed, the transfer has been marked as red. `4` — Unavailable — the AML check is unavailable for this transfer type.
`amount_target`	string	The amount that is debited from or credited to a wallet, in the wallet currency, including fees and commissions.
`commission_target`	string	This is a service field. The value is always `"0"`.
`amount_cleared`	string	The amount by which the transfer changes the wallet balance. For outgoing transfers, the value is multiplied by -1.
`sender_addresses`	array of strings or null	The blockchain addresses that sent the funds of an incoming payment. A payment may have several sender addresses. Returned only if the request sets the `sender_addresses` parameter to `true` and the capability is enabled for your account; otherwise, the field is absent from the response. `null` if the sender can’t be determined, the addresses are no longer retained, or the blockchain doesn’t support the lookup. Populated for the `op_type` values `1`, `10`, `14`, and `29` only. Every other type returns `null`, including incoming ones such as dust and staking rewards. For the type names, refer to Transfer types.
`currency`	object	The payment currency. For Enterprise wallets, always the same as the wallet currency. For Merchant wallets, may differ from the wallet currency. The object contains the string `id` field matching the currency ISO code (refer to Currency codes for possible values).
`wallet`	object	The wallet to or from which the transfer was made. The object contains the string `id` field matching the wallet system identifier.
`parent`	object	Applicable mainly for tokens. The object contains a link to the parent transfer, if the current transfer depends on the parent one. In other cases, returns `"data": null`.

The sender_addresses field is resolved at request time and isn’t stored, so the same transfer can return addresses today and null later, once the addresses are no longer retained. Filtering or sorting transfers by sender address isn’t supported.

Every callback whose body embeds a transfer object includes the sender_addresses key — no request parameter is needed. The value contains the addresses if the capability is enabled for your account, and null otherwise. Callbacks that embed no transfer object, such as an expired deposit or a rejected payout, don’t include the key. A callback resend is built from current data, so a resend after the retention window contains null.

Transfer object example

{
  "type": "transfer",
  "id": "8163",
  "attributes": {
    "op_id": 3262,
    "op_type": 14,
    "amount": "0.77700000",
    "rate_target": "1.000000000000000000",
    "commission": "0.00233100",
    "fee": "0.00000000",
    "txid": "0f82d9a82c166ed87a47b968e6a713c...",
    "status": 2,
    "user_message": null,
    "created_at": "2024-02-08T11:16:16.179799Z",
    "updated_at": "2024-02-08T11:16:17.483373Z",
    "confirmations": 191,
    "risk": 0,
    "risk_status": 4,
    "amount_target": "0.77466900",
    "commission_target": "0",
    "amount_cleared": "0.77466900",
    "sender_addresses": ["0x1f9840a85d5af5bf1d1762f925bdaddc4201f984"]
  },
  "relationships": {
    "currency": {
      "data": {
        "type": "currency",
        "id": "1000"
      }
    },
    "wallet": {
      "data": {
        "type": "wallet",
        "id": "3262"
      }
    },
    "parent": {
      "data": null
    }
  }
}

Get transfer

Request

GET [base]/transfer/{id}

Name Type Required Description

id string No The unique system identifier of a transfer.

Name	Type	Required	Description
`id`	string	No	The unique system identifier of a transfer.
`sender_addresses`	boolean	No	Include the `sender_addresses` field in the response. Accepted values: `true`, `1`, and `yes`, in any letter case. Any other value, and omitting the parameter, leaves the field out of the response. Requires the capability to be enabled for your account.

sender_addresses

boolean

Include the sender_addresses field in the response. Accepted values: true, 1, and yes, in any letter case. Any other value, and omitting the parameter, leaves the field out of the response.

Requires the capability to be enabled for your account.

Filtering by object parameters can be applied according to the JSON API Specification.

Request example

curl --request GET \
--url [base]/transfer/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/vnd.api+json'

import requests

url = '[base]/transfer/'

headers = {
  'Authorization': 'Bearer <token>',
  'Content-Type': 'application/vnd.api+json',
}

requests.get(url, headers=headers)

<?php

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new GuzzleHttp\Client();
try {
  $res = $client->get('[base]/transfer/', [
    'headers' => [
      'Authorization' => 'Bearer <token>',
      'Content-Type' => 'application/vnd.api+json',
    ],
  ]);
  echo $res->getBody();
} catch (RequestException $e) {}

Response

In case of success, the response body contains a transfer object or an array of objects (if the id wasn’t specified).

The wallets list is paginated and the default page size is 10. You can adjust pagination according to the JSON API Specification.

Response codes

HTTP code	Application code	Description	Suggested action
`200`	—	The request succeeded.	—
`400`	400: sender_addresses resolves at most 25 transactions per request, and this page needs N. Reduce page[size].	The requested page needs too many upstream lookups to resolve sender addresses. This applies to list requests only: a request for a single transfer resolves one transaction and never reaches the limit. In the message, `N` is the number of transactions the requested page needs.	Reduce the `page[size]` value.
`401`	2007: No active account found with the given credentials	Incorrect credentials.	Send correct credentials.
`403`	403: sender_addresses is not enabled for this client.	The `sender_addresses` capability isn’t enabled for your account.	Contact the Support Team to enable the capability, or omit the `sender_addresses` parameter.
`404`	404: Not found	The transfer with the given `id` wasn’t found.	Send a correct `id`.
`500`	—	Internal server error.	Try again later.
`502`	—	Bad gateway.	Try again later.
`503`	—	Service unavailable.	Try again later.
`504`	—	Gateway timeout.	Try again later.
`5xx`	—	Other server errors.	Try again later.