Getting Started

COINQVEST enables you to accept payments in Bitcoin, Ethereum, Litecoin, Stellar Lumens, or any asset on the Stellar Network and settle in USD, EUR, or other supported fiat currencies (or crypto) instead.

The COINQVEST API connects your online business, e-commerce store, or web application with cryptocurrency payments. This documentation provides information on how to interact with the API.

Using the COINQVEST API

Accepting cryptocurrency payments using the COINQVEST API is fast, secure, and easy. After you've signed up and obtained your API key, all you need to do is create a checkout to get paid.

There are two types of checkouts, hosted (by COINQVEST) and self-hosted (by you). Hosted checkouts live on COINQVEST servers and provide a fast, convenient, responsive, and easy user interface for your customers to complete payment. We built a great user experience so you don't have to. Self-hosted checkouts live on your servers and give you full control over branding and the entire payment process but require more development work.

Creating Hosted Checkouts

Hosted checkouts are the simplest form of getting paid using the COINQVEST platform. The POST /checkout/hosted API endpoint creates and returns a payment URL for a dynamic checkout page on COINQVEST servers. Your application retrieves the checkout URL and directs your customer to the hosted checkout page to complete payment.

Here is an example of how to dynamically create a hosted checkout and get paid:

Example Request

curl -X POST https://www.coinqvest.com/api/v1/checkout/hosted \
     -H "X-Digest-Key: YOUR_API_KEY" \
     -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
     -H "X-Digest-Timestamp: TIMESTAMP" \
     -d "@charge.json"

Where authentication is supplied via HTTP headers and charge.json is a JSON object:

Example Charge (minimal)

{
   "charge":{
      "currency":"USD",
      "lineItems":[
         {
            "description":"T-Shirt",
            "netAmount":10.00
         }
      ]
   }
}

Above example creates a charge for a t-shirt at 10.00 USD. You can configure more details, such as shipping costs, discounts, taxes, the related customer, or your preferred settlement currency as documented here.

Example Response (application/json)

{
   "id":"b5bcf27e5482",
   "url":"https://www.coinqvest.com/en/checkout?id=b5bcf27e5482"
}

The API returns a unique identifier along with a hosted checkout URL, which you display back to your customer in order for him or her to complete payment. Once the funds are captured we notify you via WEBHOOK checkout-completed.

Receiving Payments

Unlike credit card payments where merchants need to obtain credit card credentials in order to place a charge, cryptocurrency payments implement a push model where the customer must explicitly invoke the payment to send money to the merchant.

After creating a checkout, COINQVEST continuously observes your customer's selected blockchain to monitor inbound payments. We set a 60 minute monitoring window for the payment to complete. If your customer does not complete the payment within that time frame, we mark the payment as expired (but still accept payment if it arrives delayed).

Once the payment has been received, your balance is credited, your dashboard automatically updated, and a webhook callback sent to your server, to automatically process the order in your system (WEBHOOK checkout-completed).

Example Webhook (application/json)

{
   "eventType":"CHECKOUT_COMPLETED",
   "data":{
      "checkout":{
         "id":"efd667b61725",
         "timestamp":"2020-09-16T21:34:28+00:00",
         "state":"COMPLETED",
         "type":"HOSTED",
         "origin":"API",
         "settlementAssetId":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
         "settlementAmountRequired":"10.0000000",
         "settlementAmountReceived":"10.0000000",
         "settlementAmountFeePaid": "0",
         "sourceAssetId":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
         "sourceAmountRequired":"0.0069518",
         "sourceAmountReceived":"0.0069518",
         "sourceBlockchain":"Ethereum",
         "sourceBlockchainAssetCode":"ETH",
         "blockchainTransactions":[
            {
               "type":"ORIGIN",
               "typeDescription":"Blockchain payment transaction initiated by customer.",
               "blockchain":"Ethereum",
               "blockchainAssetCode":"ETH",
               "tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
               "amount":"0.0069518",
               "amountAssetCode":"ETH",
               "exception":null
            },
            {
               "type":"TRANSFER",
               "typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
               "blockchain":"Stellar Network",
               "blockchainAssetCode":"XLM",
               "tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
               "amount":"0.0069518",
               "amountAssetCode":"ETH",
               "exception":null
            },
            {
               "type":"SETTLEMENT",
               "typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
               "blockchain":"Stellar Network",
               "blockchainAssetCode":"XLM",
               "tx":"63dab32ba979e41e43a718aaf51c61cadf6dec944715d9fd04f1f61d9ee8800f",
               "amount":"10.0000000",
               "amountAssetCode":"USD",
               "exception":null
            }
         ],
         "payload":{
            "charge":{
               "lineItems":[
                  {
                     "description":"T-Shirt",
                     "quantity":"1",
                     "netAmount":"10",
                     "productId":"yellow"
                  }
               ],
               "currency":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
               "customerId":"a2df67b61725"
            },
            "settlementCurrency":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX"
         }
      }
   }
}

The webhook contains a JSON object in the HTTP request body and informs you about incoming payments and their attributes as specified in WEBHOOK checkout-completed. In above example the customer paid in ETH and the merchant got credited in USD.

Creating Self-Hosted Checkouts

COINQVEST APIs enable you to fully control and host the entire checkout process in your own web application and branding. Choose self-hosted checkouts if you want your users to stay within your application without being redirected to COINQVEST to complete payment. Inspect the POST /checkout API endpoint to get started with whitelabel payments.

Software Development Kits

The COINQVEST API works with any REST client in any programming language and we've published SDKs for PHP, Ruby, and NodeJS on our GitHub to help you get started quickly.

PHP
Official COINQVEST Merchant SDK for PHP

Ruby
Official COINQVEST Merchant SDK for Ruby

NodeJS
Official COINQVEST Merchant SDK for NodeJS

Developer Guides

We're continuously updating and adding to our library of COINQVEST guides and tutorials to help you understand and work with the platform as quickly and conveniently as possible. Below is a list of guides currently available on our blog.

COINQVEST Developer Guide
Cryptocurrency Payments with COINQVEST Merchant APIs

API Tools and Event Logging
An Introduction to COINQVEST's Merchant API, Developer Tools, and Event Logs

E-Commerce Integrations

We're continuously updating our e-commerce libraries, plugins and extensions to help you integrate with COINQVEST as quickly and conveniently as possible. Below is a list of e-commerce integrations currently available in production.

Wordpress
Official COINQVEST Plugin for Wordpress

WooCommerce
Official COINQVEST Plugin for WooCommerce

Shopify
Official COINQVEST Integration for Shopify

Magento
Official COINQVEST Extension for Magento 2

Not a Developer?

It's easy to receive cryptocurrency payments even if you are not a developer. Read our guide about hosted checkouts and direct invoicing.

COINQVEST for Non-Developers
Cryptocurrency Payment Processing for Non-Developers

Authentication

Most requests to the COINQVEST API must be authenticated. The API endpoints are marked as public () or protected (). When accessing a protected endpoint your request must be authenticated with your API key using either the Basic-Auth or Digest-Auth method. The latter is more secure and recommended. Try the GET /auth-test endpoint to conveniently test your authentication implementation.

API Key and Secret

Visit the API Settings to obtain your API key and API secret. You should also configure your preferred authentication method and enable "IP-address whitelisting" for increased security. If you ever feel that your API secret has been compromised, the settings allow you to roll a new one.

Digest-Auth

Digest-Auth is the recommended authentication method for accessing protected COINQVEST API endpoints. Every request must include the following headers: X-Digest-Key, X-Digest-Signature, and X-Digest-Timestamp, which are explained below.

Request

curl 'https://www.coinqvest.com/api/v1/auth-test' \
     -H "X-Digest-Key: YOUR_API_KEY" \
     -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
     -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

Request Headers

Key	Type	Description
`X-Digest-Key`	string	Your COINQVEST API key.	mandatory
`X-Digest-Signature`	string	Unique Digest-Auth Signature (see below).	mandatory
`X-Digest-Timestamp`	integer	Current Unix timestamp (also see `GET /time`).	mandatory

The X-Digest-Signature is generated by creating a SHA256 HMAC hash using your API Secret as the shared secret in the message digest. The encrypted payload is composed as follows:
ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY, where . represents string concatenation.

X-Digest-Signature Components

Component	Type	Description
`ENDPOINT_PATH`	string	The path of the endpoint that is being invoked, e.g. `/auth-test` in lower case.
`UNIX_TIMESTAMP`	integer	Current Unix timestamp. Must be less than 30 seconds old (also see `GET /time`).
`REQUEST_METHOD`	string	The request method, e.g. `POST` or `GET` in upper case.
`REQUEST_BODY`	string	The request body string. Only needed in `POST`, `PUT`, or `DELETE` requests. Set `null` for `GET` requests.

Code Example (PHP)

$path = '/auth-test'
$timestamp = time();
$method = 'GET';
$body = $method == 'GET' ? null : json_encode($params);
$secret = 'YOUR_API_SECRET';

$signature = hash_hmac('sha256', $path . $timestamp . $method . $body, $secret);

Code Example (Ruby)

require 'openssl'

path = '/auth-test'
timestamp = Time.now.to_i
method = 'GET'
body = method == 'GET' ? NIL : params.to_json
secret = 'YOUR_API_SECRET'

signature = OpenSSL::HMAC.hexdigest('sha256', secret, path + timestamp.to_s + method + body.to_s)

Code Example (NodeJS)

require('crypto');

let path = '/auth-test'
let timestamp = Date.now() / 1000 | 0;
let method = 'GET'
let body = method === 'GET' ? '' : JSON.stringify(params)
let secret = 'YOUR_API_SECRET'

let signature = crypto.createHmac('sha256', secret)
                .update(path + timestamp + method + body)
                .digest('hex');

View these examples if you're unsure how to create an HMAC SHA256 signature in your programming language.

Basic-Auth

You can choose to use a basic authentication header, which is easier to implement (as it's a static hash over your API key and secret) but less secure than Digest-Auth. We recommend use Basic-Auth during development or in test environments only.

Request

curl 'https://www.coinqvest.com/api/v1/auth-test' \
     -H "X-Basic: BASIC_AUTH_HASH"

Request Headers

Key	Type	Description
`X-Basic`	string	SHA256 hash over `YOUR_API_KEY:YOUR_API_SECRET`	mandatory

Code Example

$key = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';

$basicAuthHash = hash('sha256', $key . ':' . $secret);

IP Address Whitelisting

Use the API Settings to configure whether your API account can be accessed from any IP address or whitelisted IP addresses only. IP address whitelisting is recommended for production environments as it dramatically increases security. Withdrawal endpoints can only be accessed from whitelisted IP addresses.

Software Development Kits (SDKs)

Our Software Development Kits for PHP, Ruby, and NodeJS are here to help you quickly integrate with the COINQVEST Merchant APIs without hassle.

Below is a list of SDKs currently available on our GitHub.

PHP
Official COINQVEST Merchant SDK for PHP

1  include('CQMerchantClient.class.php');
2
3  $client = new CQMerchantClient(
4      'YOUR-API-KEY',
5      'YOUR-API-SECRET',
6      '/var/log/coinqvest.log'
7  );

View on GitHub README.md

Ruby
Official COINQVEST Merchant SDK for Ruby

1  require 'coinqvest_merchant_sdk/client'
2
3  client = CoinqvestMerchantSDK::Client.new(
4      'YOUR-API-KEY',
5      'YOUR-API-SECRET',
6      '/var/log/coinqvest-ruby.log'
7  )

View on GitHub README.md

NodeJS
Official COINQVEST Merchant SDK for NodeJS

1  require('coinqvest-merchant-sdk');
2
3  const client = new CoinqvestClient(
4      'YOUR-API-KEY',
5      'YOUR-API-SECRET'
6  );

View on GitHub README.md

POST/checkoutprotected

Invoking a checkout is the first step to get paid. This endpoint creates a self-hosted checkout on your server, which you control entirely on your own platform UI or API. If you would like to create a hosted checkout with an automated payment page on COINQVEST servers, please use POST /checkout/hosted instead.

This endpoint takes a charge object, which includes line items, optional shipping costs or discounts and taxes. It can be optionally linked to a customer and lets you specify your desired settlement currency, which can be different from what the charge is denominated in and what your customer used for payment. Upon successful completion, the endpoint returns a list of payment methods and amounts, which you display back to your customer.

Your customer then selects his preferred payment method (e.g. Bitcoin) and you submit a new request with the selected blockchain and corresponding checkout id to POST /checkout/commit. Once a checkout is committed, our system starts monitoring the blockchain for inbound payment transactions and notifies you about payment events via WEBHOOK checkout-completed.

Checkouts are unique and not re-usable. You should create a new checkout for every charge.

Example Request

curl -X POST https://www.coinqvest.com/api/v1/checkout \
     -d "@payload.json"

Where payload.json is a JSON object.

Example Payload (Minimal)

{
   "charge":{
      "currency":"USD",
      "lineItems":[
         {
            "description":"T-Shirt",
            "netAmount":10.00
         }
      ]
   }
}

Explanation of Above Payload Configuration

Above is the minimal configuration required to initiate a checkout. The charge is denominated in "USD" and has exactly one line item at a cost of USD 10.00. The required payment amount in BTC, ETH, XLM, etc. given in the API response is calculated against the total payment amount and currency given here.

Example Payload (Full)

{
   "charge":{
      "customerId":"716dad4c5e5f",
      "currency":"USD",
      "lineItems":[
         {
            "description":"T-Shirt",
            "netAmount":10,
            "quantity":1,
            "productId":"P1234"
         }
      ],
      "discountItems":[
         {
            "description":"Loyalty Discount",
            "netAmount":0.5
         }
      ],
      "shippingCostItems":[
         {
            "description":"Shipping and Handling",
            "netAmount":3.99,
            "taxable":false
         }
      ],
      "taxItems":[
         {
            "name":"CA Sales Tax",
            "percent":0.0825
         }
      ]
   },
   "settlementCurrency":"USD",
   "checkoutLanguage":"en",
   "webhook":"https://www.your-server.com/path/to/webhook",
   "blockchainRelays":{
      "ETH":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
      "BTC":"BTC:GATEMHCCKCY67ZUCKTROYN24ZYT5GK4EQZ65JJLDHKHRUZI3EUEKMTCH"
   },
   "links":{
      "cancelUrl":"https://www.merchant.com/path/to/cancel/checkout",
      "returnUrl":"https://www.merchant.com/path/to/complete/checkout"
   },
   "pageSettings":{
      "shopName":"The T-Shirt Store Ltd.",
      "displayBuyerInfo":true,
      "displaySellerInfo":true
   },
   "meta":{
      "customAttribute":"customValue"
   }
}

Request Params (POST)

PRO Tip #1 Auto-Conversion

Make sure to set the settlementCurrency parameter to automatically convert incoming funds into your preferred currency, e.g. USD.

PRO Tip #2 Customer Object Relation

Provide a charge.customerId as given by POST /customer to automatically link the checkout to a customer. Linking payments with customers helps with your accounting, provides more details in your transaction history and allows you to send out automated invoices and payment status notifications.

PRO Tip #3 Total Amount Formula

The total amount calculation is executed using the following formula.
$net = sum($lineItems) - sum($discountItems) + sum($shippingCostItems)
$taxableSum = $net - sum($shippingCostItems) + sum($taxableShippingCostItems)
$total = $net + ($taxableSum * sum($taxItems))

Key	Type	Description	Default	Mandatory
`charge{}`	object	This is the core information needed to create a checkout. It provides a charge object, which describes what products or services you want to bill, optional shipping and handling costs, discounts and tax information. It also links this checkout to a customer.	null	mandatory
`.customerId`	string(12)	Specifies the customer to which this charge relates to. Use the identifier as given by `POST /customer`. This links the charge to your customer, which helps with your accounting, provides more details in your transaction history and enables invoicing and status update emails to your customer.	null	optional
`.currency`	string	The customer facing currency in which this charge is denominated in, e.g. `USD` or `EUR`. Valid values are any fiat currency or blockchain identifiers supported by COINQVEST, such as * an `assetCode` given by `GET /fiat-currencies` * or a `nativeAssetCode` as given by `GET /blockchains`. You may use a specific asset id as given by `GET /assets`. For example, if you want to calculate payment amounts against AnchorUSD's market, you'd use that asset's identifier specifically, otherwise the platform default for each fiat currency or blockchain is used. Unless a different asset code is specified in `settlementCurrency` (see below) this is also the currency you're paid in.	null	mandatory
`.lineItems{}`	object	An object providing payment amounts and details about the charged products or services.	null	mandatory
`.description`	string	The product or service description as plain text (Unicode). Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net cost for this item in the currency provided in `charge.currency`.	null	mandatory
`.quantity`	integer	The quantity of this item. If you provide a quantity `n` then the resulting total amount charged will be `n * netAmount`	1	optional
`.productId`	string	An optional product id to link this item with a corresponding relation in your own database. Maximum of 20 characters.	null	optional
`.discountItems{}`	object	An optional object listing any potential discounts related to this payment request.	null	optional
`.description`	string	The discount description as plain text (Unicode). Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net amount for this discount in the currency provided in `charge.currency`.	null	mandatory
`.shippingCostItems{}`	object	An optional object listing any potential shipping and handling costs related to this payment request.	null	optional
`.description`	string	The shipping or handling cost description as plain text (Unicode), e.g. "Shipping Costs". Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net amount of this shipping cost in the currency provided in `charge.currency`.	null	mandatory
`.taxable`	boolean	Indicates whether this shipping cost is taxable. If set to `true` then tax calculation includes this item.	false	optional
`.taxItems{}`	object	An optional object listing any potential taxes related to this payment request.	null	optional
`.name`	string	The applied tax or tax identifier, e.g. "SALES TAX".	null	mandatory
`.percent`	numeric	The percentage of the applied tax in decimal notation, e.g. `0.0825` to represent a tax rate of `8.25%`	null	mandatory
`.settlementCurrency`	string	This specifies the currency you'll be credited in when the payment completes. For example, if you specify `USD` as settlement currency then you will be credited in `USD`. Otherwise you will be credited in the `currency` specified in the charge (see above). It is possible to select a settlement currency, which is different from the customer facing currency. If you want to get credited in the exact same currency your customer paid in (without any conversion) set this to `ORIGIN`. Other valid values are any fiat currency or blockchain identifiers supported by COINQVEST, such as * an `assetCode` given by `GET /fiat-currencies` * or a `nativeAssetCode` as given by `GET /blockchains`. You may use a specific asset id as given by `GET /assets`. For example, if you want to be credited in Circle's USDC, you'd use that asset's identifier specifically, otherwise the platform default for each fiat currency or blockchain is used.	null	mandatory
`.checkoutLanguage`	string	This specifies the language on your checkout page. For example, if you specify `de` as checkout language, your customer will be presented with a hosted checkout page in German language. Use `auto` to automatically detect the customer's main browser language. Fallback language code is `en`. Supported values are: `auto` `en` `de` `pt` `es` `pl` `fr` `fa` Query supported languages with endpoint `GET /languages`.	en	optional
`.webhook`	string	A webhook URL on your server that listens for related checkout events as specified in webhook concepts.	null	optional
`.blockchainRelays{}`	object	An optional key-value list of your preferred asset issuers. It specifies which asset issuer should be used to process incoming payments from the Bitcoin, Ethereum, or Litecoin networks. If no asset issuers are specified then the platform defaults are used. The object contains blockchain identifiers (`GET /blockchains`) as attribute keys and the `id` as given by `GET /asset-issuers` as item value.	null	optional
`.links{}`	object	An object specifying URLs with information on where to send the customer if he wishes to cancel the checkout process or when the payment successfully completed.	null	optional
`.cancelUrl`	string	Specifies where to send the customer when he wishes to cancel the checkout process. This is typically the checkout page in your web application or a shopping cart view. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify custom GET parameters alternatively.	null	optional
`.returnUrl`	string	Specifies where to send the customer when the payment successfully completed. To prevent spoofing, it is very important for your server to make a call to `GET /checkout` to confirm the receipt of payment whenever this URL is invoked. Alternatively you can rely on `WEBHOOK checkout-completed`. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify custom GET parameters alternatively.	null	optional
`.pageSettings{}`	object	An object containing display settings for the customer facing hosted checkout page. Values provided here override your global account settings.	null	optional
`.shopName`	string	Your shop or company name, which is displayed in large, bold letters on top of customer facing hosted checkout pages. If no shop name is provided, your account default is used.	null	optional
`.displayBuyerInfo`	boolean	Configures whether to display the customer's billing address on customer facing hosted checkout pages. This field is only relevant if the checkout is associated with a customer. If this field is not provided, your account default is used.	null	optional
`.displaySellerInfo`	boolean	Configures whether you want to display your own mail address on customer facing hosted checkout pages. If this field is not provided, your account default is used.	null	optional
`.meta`	object	A custom object containing arbitrary information that you would like to associate with this checkout, if any. This object is included in associated webhook payloads and API responses whenever this checkout is referenced.	true	optional

Success Response application/json

{
   "id":"c1f4c3777d60",
   "paymentMethods":[
      {
         "assetCode":"BTC",
         "blockchain":"Bitcoin",
         "paymentAmount":"0.0003672",
         "settlement":{
            "assetId":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
            "amount":"14.3394628",
            "netAmount":"14.3394628",
            "fee":"0.0000000"
         }
      },
      {
         "assetCode":"ETH",
         "blockchain":"Ethereum",
         "paymentAmount":"0.0050734",
         "settlement":{
            "assetId":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
            "amount":"14.3502846",
            "netAmount":"14.3394628",
            "fee":"0.0000000"
         }
      },
      {
         "assetCode":"LTC",
         "blockchain":"Litecoin",
         "paymentAmount":"0.0996787",
         "settlement":{
            "assetId":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
            "amount":"14.3387874",
            "netAmount":"14.3394628",
            "fee":"0.0000000"
         }
      },
      {
         "assetCode":"XLM",
         "blockchain":"Stellar Network",
         "paymentAmount":"50",
         "settlement":{
            "assetId":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
            "amount":"14.3904448",
            "netAmount":"14.3394628",
            "fee":"0.0000000"
         }
      }
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`.id`	string(12)	The identifier of the checkout. You should store this persistently to match payments and associated information against this checkout.	false
`.paymentMethods[]`	array	Contains a list of available payment methods for this checkout and associated payment amounts for your customer. The payment methods and amounts should be displayed back to your customer, prompting him to select his desired form of payment. Upon selection, your application submits a `POST /checkout/commit` and obtains the deposit information and required for your customer to make the payment. We recommend to apply your own sanity checks on the amounts given in this object and only proceed to the end user if you are satisfied with the quoted settlement and payment amounts.	false
`.assetCode`	string(3)	The asset code of the payment currency, e.g. `BTC`. Inspect `GET /blockchains` for a list of supported blockchains. Submit this `assetCode` along with the `checkoutId` to the `POST /checkout-commit` endpoint to obtain deposit information for your customer.	false
`.blockchain`	string(12)	The blockchain name in plain text.	false
`.paymentAmount`	string	The required payment amount to display back to your customer.	false
`.settlement{}`	object	An object containing information on the settlement asset and amount guaranteed to be credited to your account when the payment completes.	false
`.assetId`	string	The asset credited to your account when the payment completes. Contains an asset id as given by `GET /assets`.	false
`.amount`	string	The gross amount credited to your account when the payment completes.	false
`.netAmount`	string	The net amount credited to your account when the payment completes. This amount is constituted by the `amount` minus `fee`.	false
`.fee`	string	The settlement fee collected by COINQVEST.	false

Next Step

Your application displays the payment methods received in the response back to your customer. The customer then selects his preferred payment method and your server submits this selection in a new API request to the POST /checkout/commit endpoint. In return you receive the deposit address for the selected blockchain for display to your customer. Continue here.

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/checkout/commitprotected

This endpoint is a continuation of the checkout process started in POST /checkout. If you aren't familiar with how to initialize a checkout process yet, please start here.

This endpoint takes a checkoutId and an assetCode as given by POST /checkout. Upon successful completion, it returns deposit information, which is displayed back to your customer in order for him or her to make the payment.

When the payment completes your server is automatically notified via WEBHOOK checkout-completed. Alternatively you can poll GET /checkout for payment updates after you displayed the deposit information to your customer.

In the previous step POST /checkout has given you a list of payment methods, like this:

Example Response (as given by `POST /checkout`)

{
   "id":"c1f4c3777d60",
   "paymentMethods":[
      {
         "assetCode":"BTC",
         "blockchain":"Bitcoin",
         "paymentAmount":"0.0003672",
         "settlement":{
            "assetId":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
            "amount":"14.3394628"
         }
      },
      {
         "assetCode":"ETH",
         "blockchain":"Ethereum",
         "paymentAmount":"0.0050734",
         "settlement":{
            "assetId":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
            "amount":"14.3502846"
         }
      },
      {
         "assetCode":"LTC",
         "blockchain":"Litecoin",
         "paymentAmount":"0.0996787",
         "settlement":{
            "assetId":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
            "amount":"14.3387874"
         }
      },
      {
         "assetCode":"XLM",
         "blockchain":"Stellar Network",
         "paymentAmount":"50",
         "settlement":{
            "assetId":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
            "amount":"14.3904448"
         }
      }
   ]
}

As a prerequisite to invoke this endpoint you should have received a response as above from POST /checkout. It contains a list of payment methods, which you display back to your customer to choose from. Upon selection, you invoke POST /checkout/commit (this endpoint) with the selected assetCode and checkoutId to receive deposit information for your customer to make the payment.

Request

curl -X POST 'https://www.coinqvest.com/api/v1/checkout/commit'
     -d "@payload.json"

Where payload.json is a JSON object.

Example Payload

{
  "checkoutId":"6d55626309d6",
  "assetCode":"ETH"
}

Request Params

Key	Type	Description	Default	Mandatory
`checkoutId`	string(12)	Unique identifier as given by `POST /checkout`.	null	mandatory
`assetCode`	string(3)	The asset code related to the payment method selected by your customer, e.g. `ETH` if your customer wishes to pay using the Ethereum blockchain.	null	mandatory

Example Success Response for ETH application/json

{
   "depositInstructions":{
      "blockchain":"Ethereum",
      "assetCode":"ETH",
      "amount":"0.0056804",
      "address":"0xc85eBb197c8212C09B7d0905C3ce9e3fCe324F0B",
      "memo":null,
      "memoType":null,
      "destinationTag":null
   },
   "settlement": {
       "assetId": "USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
       "amount": "19.2514345"
   },
   "expirationTime":"2020-02-26T18:49:33+00:00",
   "checkoutId":"29d030183ce9"
}

When you customer selects Bitcoin (BTC), Ethereum (ETH) or Litecoin (LTC) as their payment method of choice, the only relevant fields are address and amount. The response fields for memo, memoType and destinationTag are null and irrelevant in these cases. You don't need to display them to the customer.

Example Success Response for XLM application/json

{
   "depositInstructions":{
      "blockchain":"Stellar Network",
      "assetCode":"XLM",
      "amount":"17.8639906",
      "address":"GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ",
      "memo":"snowy-hills",
      "memoType":"text",
      "destinationTag":null
   },
   "settlement": {
       "assetId": "USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
       "amount": "2.3354345"
   },
   "expirationTime":"2020-02-26T18:48:58+00:00",
   "checkoutId":"d95114c52bca"
}

When your customers select XLM as their payment currency then you need to provide them with the address as well as memo and memoType. This is important in order for COINQVEST to map the payment to your merchant account. The destinationTag field is null and irrelevant for XLM payments and can be ignored.

Success Response Attributes

Name	Type	Description	Nullable
`.depositInstructions{}`	object	The deposit information to display to your customer.	false
`.blockchain`	string	The selected blockchain name as plain text.	false
`.assetCode`	string(3)	The selected payment asset code, e.g. `BTC`, `ETH`, `XLM`, or `LTC`.	false
`.amount`	string	The required payment amount for the selected blockchain. Display this back to your customer. Please note that this field is of type `string` even though it is numeric. You might need to do some type casting here.	false
`.memo`	string	This field is only relevant for payments in `XLM`. Otherwise it is `null`. If the `assetCode` is `XLM`, it is extremely important to display this back to your customer alongside the deposit address because it is needed to map the payment to your merchant account.	true
`.memoType`	string	This field is only relevant for payments in `XLM`. Otherwise it is `null`. If the `assetCode` is `XLM`, it is extremely important to display this back to your customer alongside the deposit address because it is needed to map the payment to your merchant account.	true
`.settlement{}`	object	An object containing information on the settlement asset and amount guaranteed to be credited to your account when the payment completes.	false
`.assetId`	string	The asset credited to your account when the payment completes. Contains an asset id as given by `GET /assets`.	false
`.amount`	string	The amount credited to your account when the payment completes.	false
`.expirationTime`	timestamp	W3C formatted timestamp with the expiration time for this checkout. COINQVEST allows for a 60 minute window to complete the payment, afterwards we mark the charge as expired. Don't worry though, you will still be credited even if the payment arrives late.	false
`.checkoutId`	array	The checkout id as originally given by `POST /checkout`.	false

Next Step

You display the deposit information back to your customer. Meanwhile COINQVEST starts monitoring the blockchain address given in the API response above and notifies you automatically via WEBHOOK checkout-completed when a payment completes. Alternatively you can poll GET /checkout for payment updates after you displayed the deposit information to your customer.

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/checkout/hostedprotected

Hosted checkouts are the simplest form of getting paid using the COINQVEST platform. This API endpoint creates and returns a URL for a hosted checkout page on COINQVEST servers. If you would like to maintain control of the UI and entire checkout process yourself, please use the POST /checkout endpoint instead.

Using this endpoint, your server submits a set of parameters, such as the payment details including optional tax items, customer information, and settlement currency. Your server then receives a checkout URL in return, which is displayed back to your customer.

Upon visiting the URL, your customer is presented with a checkout page hosted on COINQVEST servers. This page displays all the information the customer needs to complete payment. When completed, your application is automatically notified via WEBHOOK checkout-completed. Alternatively you can poll GET /checkout to query information about the payment state.

COINQVEST hosted checkouts implement responsive design and are suitable for mobile phone screens as well as desktop environments with large monitors.

Hosted checkout URLs are unique and not re-usable. You should issue a new URL for every charge.

Example Request

curl -X POST https://www.coinqvest.com/api/v1/checkout/hosted \
     -d "@payload.json"

Where payload.json is a JSON object.

Example Payload (Minimal)

{
   "charge":{
      "currency":"USD",
      "lineItems":[
         {
            "description":"T-Shirt",
            "netAmount":10.00
         }
      ]
   }
}

Explanation of Above Payload Configuration

Above is the minimal configuration required to initiate a checkout. The charge is denominated in "USD" and has exactly one line item at a cost of USD 10.00. The required payment amount in BTC, ETH, XLM, etc. given in the API response is calculated against the total payment amount and currency given here.

Example Payload (Full)

{
   "charge":{
      "customerId":"716dad4c5e5f",
      "currency":"USD",
      "lineItems":[
         {
            "description":"T-Shirt",
            "netAmount":10,
            "quantity":1,
            "productId":"P1234"
         }
      ],
      "discountItems":[
         {
            "description":"Loyalty Discount",
            "netAmount":0.5
         }
      ],
      "shippingCostItems":[
         {
            "description":"Shipping and Handling",
            "netAmount":3.99,
            "taxable":false
         }
      ],
      "taxItems":[
         {
            "name":"CA Sales Tax",
            "percent":0.0825
         }
      ]
   },
   "settlementCurrency":"USD",
   "checkoutLanguage":"en",
   "webhook":"https://www.your-server.com/path/to/webhook",
   "blockchainRelays":{
      "ETH":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
      "BTC":"BTC:GATEMHCCKCY67ZUCKTROYN24ZYT5GK4EQZ65JJLDHKHRUZI3EUEKMTCH"
   },
   "links":{
      "cancelUrl":"https://www.merchant.com/path/to/cancel/checkout",
      "returnUrl":"https://www.merchant.com/path/to/complete/checkout"
   },
   "pageSettings":{
      "shopName":"The T-Shirt Store Ltd.",
      "displayBuyerInfo":true,
      "displaySellerInfo":true
   },
   "meta":{
      "customAttribute":"customValue"
   }
}

Request Params (POST)

PRO Tip #1 Auto-Conversion

Make sure to set the settlementCurrency parameter to automatically convert incoming funds into your preferred currency, e.g. USD.

PRO Tip #2 Customer Object Relation

Provide a charge.customerId as given by POST /customer to automatically link the checkout to a customer. Linking payments with customers helps with your accounting, provides more details in your transaction history and allows you to send out automated invoices and payment status notifications.

PRO Tip #3 Total Amount Formula

The total amount calculation is executed using the following formula.
$net = sum($lineItems) - sum($discountItems) + sum($shippingCostItems)
$taxableSum = $net - sum($shippingCostItems) + sum($taxableShippingCostItems)
$total = $net + ($taxableSum * sum($taxItems))

Key	Type	Description	Default	Mandatory
`charge{}`	object	This is the core information needed to create a checkout. It provides a charge object, which describes what products or services you want to bill, optional shipping and handling costs, discounts and tax information. It also links this checkout to a customer.	null	mandatory
`.customerId`	string(12)	Specifies the customer to which this charge relates to. Use the identifier as given by `POST /customer`. This links the charge to your customer, which helps with your accounting, provides more details in your transaction history and enables invoicing and status update emails to your customer.	null	optional
`.currency`	string	The customer facing currency in which this charge is denominated in, e.g. `USD` or `EUR`. Valid values are any fiat currency or blockchain identifiers supported by COINQVEST, such as * an `assetCode` given by `GET /fiat-currencies` * or a `nativeAssetCode` as given by `GET /blockchains`. You may use a specific asset id as given by `GET /assets`. For example, if you want to calculate payment amounts against AnchorUSD's market, you'd use that asset's identifier specifically, otherwise the platform default for each fiat currency or blockchain is used. Unless a different asset code is specified in `settlementCurrency` (see below) this is also the currency you're paid in.	null	mandatory
`.lineItems{}`	object	An object providing payment amounts and details about the charged products or services.	null	mandatory
`.description`	string	The product or service description as plain text (Unicode). Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net cost for this item in the currency provided in `charge.currency`.	null	mandatory
`.quantity`	integer	The quantity of this item. If you provide a quantity `n` then the resulting total amount charged will be `n * netAmount`	1	optional
`.productId`	string	An optional product id to link this item with a corresponding relation in your own database. Maximum of 20 characters.	null	optional
`.discountItems{}`	object	An optional object listing any potential discounts related to this payment request.	null	optional
`.description`	string	The discount description as plain text (Unicode). Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net amount for this discount in the currency provided in `charge.currency`.	null	mandatory
`.shippingCostItems{}`	object	An optional object listing any potential shipping and handling costs related to this payment request.	null	optional
`.description`	string	The shipping or handling cost description as plain text (Unicode), e.g. "Shipping Costs". Maximum of 200 characters.	null	mandatory
`.netAmount`	numeric	The net amount of this shipping cost in the currency provided in `charge.currency`.	null	mandatory
`.taxable`	boolean	Indicates whether this shipping cost is taxable. If set to `true` then tax calculation includes this item.	false	optional
`.taxItems{}`	object	An optional object listing any potential taxes related to this payment request.	null	optional
`.name`	string	The applied tax or tax identifier, e.g. "SALES TAX".	null	mandatory
`.percent`	numeric	The percentage of the applied tax in decimal notation, e.g. `0.0825` to represent a tax rate of `8.25%`	null	mandatory
`.settlementCurrency`	string	This specifies the currency you'll be credited in when the payment completes. For example, if you specify `USD` as settlement currency then you will be credited in `USD`. Otherwise you will be credited in the `currency` specified in the charge (see above). It is possible to select a settlement currency, which is different from the customer facing currency. If you want to get credited in the exact same currency your customer paid in (without any conversion) set this to `ORIGIN`. Other valid values are any fiat currency or blockchain identifiers supported by COINQVEST, such as * an `assetCode` given by `GET /fiat-currencies` * or a `nativeAssetCode` as given by `GET /blockchains`. You may use a specific asset id as given by `GET /assets`. For example, if you want to be credited in Circle's USDC, you'd use that asset's identifier specifically, otherwise the platform default for each fiat currency or blockchain is used.	null	mandatory
`.checkoutLanguage`	string	This specifies the language on your checkout page. For example, if you specify `de` as checkout language, your customer will be presented with a hosted checkout page in German language. Use `auto` to automatically detect the customer's main browser language. Fallback language code is `en`. Supported values are: `auto` `en` `de` `pt` `es` `pl` `fr` `fa` Query supported languages with endpoint `GET /languages`.	en	optional
`.webhook`	string	A webhook URL on your server that listens for related checkout events as specified in webhook concepts.	null	optional
`.blockchainRelays{}`	object	An optional key-value list of your preferred asset issuers. It specifies which asset issuer should be used to process incoming payments from the Bitcoin, Ethereum, or Litecoin networks. If no asset issuers are specified then the platform defaults are used. The object contains blockchain identifiers (`GET /blockchains`) as attribute keys and the `id` as given by `GET /asset-issuers` as item value.	null	optional
`.links{}`	object	An object specifying URLs with information on where to send the customer if he wishes to cancel the checkout process or when the payment successfully completed.	null	optional
`.cancelUrl`	string	Specifies where to send the customer when he wishes to cancel the checkout process. This is typically the checkout page in your web application or a shopping cart view. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify custom GET parameters alternatively.	null	optional
`.returnUrl`	string	Specifies where to send the customer when the payment successfully completed. To prevent spoofing, it is very important for your server to make a call to `GET /checkout` to confirm the receipt of payment whenever this URL is invoked. Alternatively you can rely on `WEBHOOK checkout-completed`. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify custom GET parameters alternatively.	null	optional
`.pageSettings{}`	object	An object containing display settings for the customer facing hosted checkout page. Values provided here override your global account settings.	null	optional
`.shopName`	string	Your shop or company name, which is displayed in large, bold letters on top of customer facing hosted checkout pages. If no shop name is provided, your account default is used.	null	optional
`.displayBuyerInfo`	boolean	Configures whether to display the customer's billing address on customer facing hosted checkout pages. This field is only relevant if the checkout is associated with a customer. If this field is not provided, your account default is used.	null	optional
`.displaySellerInfo`	boolean	Configures whether you want to display your own mail address on customer facing hosted checkout pages. If this field is not provided, your account default is used.	null	optional
`.meta`	object	A custom object containing arbitrary information that you would like to associate with this checkout, if any. This object is included in associated webhook payloads and API responses whenever this checkout is referenced.	true	optional

Success Response application/json

{
   "id":"b5bcf27e5482",
   "url":"https://www.coinqvest.com/en/checkout?id=b5bcf27e5482",
   "oracle":[
      {
         "assetCode":"BTC",
         "blockchain":"Bitcoin",
         "paymentAmount":"0.0002513",
         "settlement":{
            "assetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "amount":"10.00",
            "netAmount":"10.00",
            "fee":"0.00"
         }
      },
      {
         "assetCode":"ETH",
         "blockchain":"Ethereum",
         "paymentAmount":"0.0034697",
         "settlement":{
            "assetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "amount":"10.00",
            "netAmount":"10.00",
            "fee":"0.00"
         }
      },
      {
         "assetCode":"LTC",
         "blockchain":"Litecoin",
         "paymentAmount":"0.0924672",
         "settlement":{
            "assetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "amount":"10.00",
            "netAmount":"10.00",
            "fee":"0.00"
         }
      },
      {
         "assetCode":"XLM",
         "blockchain":"Stellar Network",
         "paymentAmount":"49.4406172",
         "settlement":{
            "assetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "amount":"10.00",
            "netAmount":"10.00",
            "fee":"0.00"
         }
      }
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`.id`	string(12)	The identifier of the hosted checkout. You should store this persistently to match payments against this checkout.	false
`.url`	string(12)	The hosted checkout URL, which you display back to your customer to initiate payment. Upon visiting this URL your client is presented with a checkout interface where he completes the payment. When completed, your application is automatically notified via `WEBHOOK checkout-completed`. Alternatively you can poll `GET /checkout` using the `id` given in the above response to query information about the payment state. Returns branded URL if Brand Connect is enabled.	false
`.oracle[]`	array	Contains a list of available payment methods for this checkout alongside indicative payment amounts and corresponding indicative settlement amounts. The given amounts are an estimation and and based on the current liquidity and market making situation on COINQVEST's decentralized exchange provider. The payment amounts can deviate by the time the buyer initiates payment on the checkout page. We recommend to apply your own sanity checks on the amounts given in this object and only display the checkout URL to the end user if you are satisfied with the quoted settlement and payment amount estimations.	false
`.assetCode`	string(3)	The asset code of the payment currency, e.g. `BTC`.	false
`.blockchain`	string(12)	The blockchain name in plain text.	false
`.paymentAmount`	string	The required payment amount currently needed to fill your settlement amount. This amount can deviate on the customer facing payment page.	false
`.settlement{}`	object	An object containing information on the settlement asset and amount to be credited to your account when the payment completes.	false
`.assetId`	string	The asset credited to your account when the payment completes. Contains an asset id as given by `GET /assets`.	false
`.amount`	string	The gross amount credited to your account when the payment completes. This amount can deviate upon completion of payment unless your billing and settlement currencies are equal.	false
`.netAmount`	string	The net amount credited to your account when the payment completes. This amount is constituted by the `amount` minus `fee`. This amount can deviate upon completion of payment unless your billing and settlement currencies are equal.	false
`.fee`	string	The settlement fee collected by COINQVEST.	false

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/checkoutprotected

Retrieves information about a given checkout.

The response of this endpoint contains information about blockchain payments associated with this checkout, its overall completion state, as well as additional meta information.

This endpoint is suitable for polling payment events associated with the given checkout. An adequate alternative is listening for payment events using WEBHOOK checkout-completed on your server.

Request

curl 'https://www.coinqvest.com/api/v1/checkout?id=xxx'

Request Params

Key	Type	Description	Default	Mandatory
`id`	string(12)	Unique identifier as given by `POST /checkout` or `POST /checkout/hosted`.	null	mandatory

Success Response application/json

{
   "checkout":{
      "id":"efd667b61725",
      "timestamp":"2020-09-16T21:34:28+00:00",
      "state":"COMPLETED",
      "type":"HOSTED",
      "origin":"API",
      "settlementAssetId":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
      "settlementAmountRequired":"10.0000000",
      "settlementAmountReceived":"10.0000000",
      "settlementAmountFeePaid": "0",
      "sourceAssetId":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
      "sourceAmountRequired":"0.0069518",
      "sourceAmountReceived":"0.0069518",
      "sourceBlockchain":"Ethereum",
      "sourceBlockchainAssetCode":"ETH",
      "blockchainTransactions":[
         {
            "type":"ORIGIN",
            "typeDescription":"Blockchain payment transaction initiated by customer.",
            "blockchain":"Ethereum",
            "blockchainAssetCode":"ETH",
            "tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
            "amount":"0.0069518",
            "amountAssetCode":"ETH",
            "exception":null
         },
         {
            "type":"TRANSFER",
            "typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
            "blockchain":"Stellar Network",
            "blockchainAssetCode":"XLM",
            "tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
            "amount":"0.0069518",
            "amountAssetCode":"ETH",
            "exception":null
         },
         {
            "type":"SETTLEMENT",
            "typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
            "blockchain":"Stellar Network",
            "blockchainAssetCode":"XLM",
            "tx":"63dab32ba979e41e43a718aaf51c61cadf6dec944715d9fd04f1f61d9ee8800f",
            "amount":"10.0000000",
            "amountAssetCode":"USD",
            "exception":null
         }
      ],
      "payload":{
         "charge":{
            "lineItems":[
               {
                  "description":"T-Shirt",
                  "quantity":"1",
                  "netAmount":"10",
                  "productId":"yellow"
               }
            ],
            "currency":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
            "customerId":"a2df67b61725"
         },
         "settlementCurrency":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX"
      }
   }
}

Success Response Attributes

;

Name	Type	Description	Nullable
`.checkout{}`	array	The checkout object.	false
`.id`	string(12)	Unique identifier of the checkout.	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the checkout was created.	false
`.state`	string	Indicates the current payment state associated with this checkout. A state of `COMPLETED` indicates this checkout has completed and the funds were credited to your account. Possible payment states: `PENDING_CHARGE`, `NEW_CHARGE`, `IN_PROGRESS`, `COMPLETED`, `EXPIRED`, `UNRESOLVED_GENERIC`, `UNRESOLVED_UNDERPAID`, `REFUNDED`.	false
`.type`	string	Indicates whether this is a hosted (`HOSTED`) or self-hosted (`SELF-HOSTED`) checkout.	false
`.origin`	string	Indicates whether this checkout was originally created via `UI` or `API`.	false
`.settlementAssetId`	string	The settlement asset used for this checkout. Indicates the asset (`GET /assets`) you are credited in when the checkout is complete.	false
`.settlementAmountRequired`	string	Indicates the total gross amount credited to your account when the checkout is complete. Is `null` when the customer did not select a payment currency yet.	true
`.settlementAmountReceived`	string	The net amount credited to your account. These funds are instantly available for withdrawal.	false
`.settlementAmountFeePaid`	string	The processing fee collected by COINQVEST.	false
`.sourceAssetId`	string	The payment asset (`GET /assets`) used for this checkout. Indicates the blockchain and payment method selected by the customer. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceAmountRequired`	string	Indicates the total amount payable by the customer to complete this checkout. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceAmountReceived`	string	The total amount paid by the customer so far. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceBlockchain`	string	The payment blockchain (`GET /blockchains`) selected by the customer in English plain text. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceBlockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) selected by the customer. This field is null if the customer did not select any payment method for this checkout yet.	true
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this checkout.	false
`.type`	string	The type of blockchain transaction. Can be either `CHECKOUT_ORIGIN` (blockchain payment transaction initiated by the sender, `CHECKOUT_TRANSFER` (asset issuer fund transfer from native blockchain to Stellar Network), or `CHECKOUT_SETTLEMENT` (Stellar transaction crediting your COINQVEST merchant account).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.blockchain`	string	The blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.blockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.exception`	string	An exception identifier that is set when a processing error or other exception occurred when handling this transaction. This is field is typically `null`. Possible exceptions: `CONVERSION_FAILED`, `CHECKOUT_ALREADY_COMPLETED`, `GENERIC`.	true
`.payload{}`	object	The checkout payload as originally submitted by you to `POST /checkout` or `POST /checkout/hosted`.	false

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/checkoutsprotected

Retrieves a list of checkout objects (in descending order from newest to oldest).

Request

curl 'https://www.coinqvest.com/api/v1/checkouts?limit=250&offset=0'

Request Params

Key	Type	Description	Default	Mandatory
`limit`	integer	Maximum number of checkout objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Success Response application/json

{
   "count":67,
   "limit":1,
   "offset":0,
   "checkouts":[
      {
         "id":"efd667b61725",
         "timestamp":"2020-09-16T21:34:28+00:00",
         "state":"COMPLETED",
         "type":"HOSTED",
         "origin":"API",
         "settlementAssetId":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
         "settlementAmountRequired":"10.0000000",
         "settlementAmountReceived":"10.0000000",
         "settlementAmountFeePaid": "0",
         "sourceAssetId":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
         "sourceAmountRequired":"0.0069518",
         "sourceAmountReceived":"0.0069518",
         "sourceBlockchain":"Ethereum",
         "sourceBlockchainAssetCode":"ETH",
         "blockchainTransactions":[
            {
               "type":"ORIGIN",
               "typeDescription":"Blockchain payment transaction initiated by customer.",
               "blockchain":"Ethereum",
               "blockchainAssetCode":"ETH",
               "tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
               "amount":"0.0069518",
               "amountAssetCode":"ETH",
               "exception":null
            },
            {
               "type":"TRANSFER",
               "typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
               "blockchain":"Stellar Network",
               "blockchainAssetCode":"XLM",
               "tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
               "amount":"0.0069518",
               "amountAssetCode":"ETH",
               "exception":null
            },
            {
               "type":"SETTLEMENT",
               "typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
               "blockchain":"Stellar Network",
               "blockchainAssetCode":"XLM",
               "tx":"63dab32ba979e41e43a718aaf51c61cadf6dec944715d9fd04f1f61d9ee8800f",
               "amount":"10.0000000",
               "amountAssetCode":"USD",
               "exception":null
            }
         ],
         "payload":{
            "charge":{
               "lineItems":[
                  {
                     "description":"T-Shirt",
                     "quantity":"1",
                     "netAmount":"10",
                     "productId":"yellow"
                  }
               ],
               "currency":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
               "customerId":"a2df67b61725"
            },
            "settlementCurrency":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX"
         }
      }
   ]
}

Success Response Attributes

;

Name	Type	Description	Nullable
`.count`	integer	The total number of checkout URLs in existence for this account.	false
`.limit`	integer	The limit argument used in this request.	false
`.offset`	integer	The pagination offset used in this request.	false
`.checkouts[]`	array	A list of checkout objects.	false
`.id`	string(12)	Unique identifier of the checkout.	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the checkout was created.	false
`.state`	string	Indicates the current payment state associated with this checkout. A state of `COMPLETED` indicates this checkout has completed and the funds were credited to your account. Possible payment states: `PENDING_CHARGE`, `NEW_CHARGE`, `IN_PROGRESS`, `COMPLETED`, `EXPIRED`, `UNRESOLVED_GENERIC`, `UNRESOLVED_UNDERPAID`, `REFUNDED`.	false
`.type`	string	Indicates whether this is a hosted (`HOSTED`) or self-hosted (`SELF-HOSTED`) checkout.	false
`.origin`	string	Indicates whether this checkout was originally created via `UI` or `API`.	false
`.settlementAssetId`	string	The settlement asset used for this checkout. Indicates the asset (`GET /assets`) you are credited in when the checkout is complete.	false
`.settlementAmountRequired`	string	Indicates the total gross amount credited to your account when the checkout is complete. Is `null` when the customer did not select a payment currency yet.	true
`.settlementAmountReceived`	string	The net amount credited to your account. These funds are instantly available for withdrawal.	false
`.settlementAmountFeePaid`	string	The processing fee collected by COINQVEST.	false
`.sourceAssetId`	string	The payment asset (`GET /assets`) used for this checkout. Indicates the blockchain and payment method selected by the customer. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceAmountRequired`	string	Indicates the total amount payable by the customer to complete this checkout. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceAmountReceived`	string	The total amount paid by the customer so far. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceBlockchain`	string	The payment blockchain (`GET /blockchains`) selected by the customer in English plain text. This field is null if the customer did not select any payment method for this checkout yet.	true
`.sourceBlockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) selected by the customer. This field is null if the customer did not select any payment method for this checkout yet.	true
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this checkout.	false
`.type`	string	The type of blockchain transaction. Can be either `CHECKOUT_ORIGIN` (blockchain payment transaction initiated by the sender, `CHECKOUT_TRANSFER` (asset issuer fund transfer from native blockchain to Stellar Network), or `CHECKOUT_SETTLEMENT` (Stellar transaction crediting your COINQVEST merchant account).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.blockchain`	string	The blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.blockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.exception`	string	An exception identifier that is set when a processing error or other exception occurred when handling this transaction. This is field is typically `null`. Possible exceptions: `CONVERSION_FAILED`, `CHECKOUT_ALREADY_COMPLETED`, `GENERIC`.	true
`.payload{}`	object	The checkout payload as originally submitted by you to `POST /checkout` or `POST /checkout/hosted`.	false

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/walletsprotected

Returns a list of all wallets in your account, along with the corresponding balances.

Request

curl 'https://www.coinqvest.com/api/v1/wallets'

Success Response application/json

{
   "wallets":[
      {
         "assetCode":"XLM",
         "type":"CRYPTO",
         "balance":"950.9263842",
         "assets":[
            {
               "id":"XLM:NATIVE",
               "issuerName":"Stellar Development Foundation (SDF)",
               "issuerDomain":"stellar.org",
               "balance":"950.9263842",
               "path":"/api/v1/asset?id=XLM:NATIVE"
            }
         ]
      },
      {
         "assetCode":"USD",
         "type":"FIAT",
         "balance":"10.835825",
         "assets":[
            {
               "id":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
               "issuerName":"AnchorUSD",
               "issuerDomain":"anchorusd.com",
               "balance":"10.835825",
               "path":"/api/v1/asset?id=USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX"
            }
         ]
      }
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`.wallets[]`	array	A list objects, representing the wallets in your account.	false
`.assetCode`	string(3)	The wallet's asset code, e.g. BTC or USD.	false
`.type`	string	The wallet type, i.e. `FIAT` or `CRYPTO`.	false
`.balance`	numeric	The total balance in this wallet. This is the sum of all asset balances held in this wallet, see below.	false
`.assets[]`	array	A list of objects, representing the assets held in this wallet, along with their corresponding balances.	false
`.id`	string	The unique id of asset. For the machines among us.	false
`.issuerName`	string	The name of the asset issuer.	false
`.issuerDomain`	string	The asset issuer's domain.	false
`.balance`	string	The amount of this asset currently held in this wallet.	false
`.path`	string	Invoke this endpoint to obtain more information about this asset. See `GET /asset`.	false

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/walletprotected

Retrieves wallet details based on the given assetCode.

Request

curl 'https://www.coinqvest.com/api/v1/wallet?assetCode=XXX'

Request Params

Key	Type	Description	Default	Mandatory
`assetCode`	string(3)	Specifies which wallet to retrieve, e.g. `BTC` or `USD`	-	mandatory

Success Response application/json

{
   "wallet":{
      "assetCode":"USD",
      "type":"FIAT",
      "balance":"10.835825",
      "assets":[
         {
            "id":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
            "issuerName":"AnchorUSD",
            "issuerDomain":"anchorusd.com",
            "balance":"10.835825",
            "path":"/api/v1/asset?id=USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX"
         }
      ]
   }
}

Success Response Attributes

Name	Type	Description	Nullable
`.wallet{}`	array	An object containing information about the wallet.	false
`.assetCode`	string(3)	The wallet's asset code, e.g. BTC or USD.	false
`.type`	string	The wallet type, i.e. `FIAT` or `CRYPTO`.	false
`.balance`	numeric	The total balance in this wallet. This is the sum of all asset balances held in this wallet, see below.	false
`.assets[]`	array	A list of objects, representing the assets held in this wallet, along with their corresponding balances.	false
`.id`	string	The unique id of asset. For the machines among us.	false
`.issuerName`	string	The name of the asset issuer.	false
`.issuerDomain`	string	The asset issuer's domain.	false
`.balance`	string	The amount of this asset currently held in this wallet.	false
`.path`	string	Invoke this endpoint to obtain more information about this asset. See `GET /asset`.	false

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/depositprotected

Returns an address for a direct deposit of an arbitrary amount by yourself. Direct deposits aren't associated with a checkout process or invoice and can be used to fund your account by yourself. The best analogy for its use case is a direct deposit to your bank account.

This endpoint credits you in the source currency. If you deposit BTC, for example, you will be credited in BTC. If you would like to get credited in a different currency than what you send, please use the POST /swap-deposit endpoint instead.

Deposit objects are not re-usable. You should create new deposit requests for each intended deposit transaction.

Request

curl -X POST https://www.coinqvest.com/api/v1/deposit \
     -d "@payload.json"

Where payload.json is a JSON object.

Example Payload

{
   "sourceNetworkCode":"BTC"
}

Request Params (POST)

Key	Type	Description	Nullable	Mandatory
`sourceNetworkCode`	string	Specifies the network you are going to use to make the deposit. Can be a blockchain asset code as given by `GET /blockchains` or fiat currency asset code as given by `GET /fiat-currencies`. Examples Use `BTC` to make a deposit using native Bitcoin Use `EUR` to make a fiat deposit in EUR (SEPA) Use `XLM` to make a deposit in any supported asset on the Stellar Network. Specify the sending asset by setting the `sourceAssetIssuer` parameter (see below).	false	mandatory
`sourceAssetIssuer`	string	Optionally specifies the issuer of the asset you are going to send. Use an identifier as given by `GET /asset-issuers`. If no asset issuer is specified then the platform default for the selected network is used. We recommend to leave this field empty for deposits other than via the Stellar Network. Examples To send Euro tokens on the Stellar Network, set the `sourceNetworkCode` to `XLM` and use `EURT:GAP5L...OOS2S`. To send Lumens on the Stellar Network, do not provide this parameter (the platform default for the Stellar Network already is XLM) or set it to `XLM:NATIVE` explicitly. To enforce a specific anchor for your Bitcoin, Ethereum, Litecoin, or fiat deposit, please use the anchor's asset issuer id as given by `GET /asset-issuers` (advanced).	true	optional
`.customerId`	string(12)	Specifies a customer related to this deposit, if any. Please use the identifier as given by `POST /customer`.	true	optional
`.meta`	object	A custom object containing arbitrary information that you would like to associate with this deposit, if any. This object is included in associated webhook payloads and API responses whenever this deposit is referenced.	true	optional
`.webhook`	string	A webhook URL on your server that listens for related deposit events as specified in webhook concepts.	null	optional

Success Response application/json

{
   "deposit":{
      "id":"5074f4ee055d",
      "type":"DIRECT",
      "state":"AWAITING_DEPOSIT",
      "origin":"API",
      "createTime":"2021-05-06T22:15:37+00:00",
      "completeTime":null,
      "expireTime":null,
      "sourceNetworkCode":"BTC",
      "sourceNetworkName":"Bitcoin",
      "depositAddress":"bc1q9wlypnrpxtaynswkl2culgz2l6ffsd2xwu5zdlfc7dfxd5lsaxpqw3akmf",
      "sourceAmountRequired":"ARBITRARY_AMOUNT",
      "sourceAmountReceived":"0",
      "sourceAmountMin":"0.0002",
      "sourceAmountMax":null,
      "sourceAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
      "creditAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
      "creditAmountGross":null,
      "creditAmountFee":null,
      "creditAmountNet":null,
      "creditAmountNetReceived":"0",
      "blockchainTransactions":[],
      "customerId":null,
      "meta":null,
      "failover": false,
      "failoverType": null,
      "failoverParentId": null,
      "webhook":"https://www.your-server.com/path/to/webhook"
   }
}

Success Response Attributes

Name	Type	Description	Nullable
`.deposit{}`	object	An object with deposit information.	false
`.id`	string(12)	Unique identifier of this deposit.	false
`.type`	string	The deposit type. Either `DIRECT` for direct deposits without currency conversion or `SWAP` for deposits involving a currency swap.	false
`.state`	string	The deposit state. The list of possible values is `COMPLETED` , `AWAITING_DEPOSIT`, `PROCESSING`, `PENDING_API_COMMIT` and `FAILED`.	false
`.origin`	string	Indicates how the deposit was initiated, either `UI` or `API`.	false
`.createTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was created.	false
`.completeTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was completed. This value is set when the deposit state is `COMPLETED` and otherwise it is null.	true
`.expireTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. This value only set for deposits of type `SWAP` and otherwise it is null. Please make deposit before the expiration time to ensure currency conversion. If the deposit is made after the expiration time, you might be credited in the source currency instead.	true
`.sourceNetworkCode`	string(3)	Specifies the network used to make the deposit. Can be a blockchain asset code as given by `GET /blockchains` or fiat currency asset code as given by `GET /fiat-currencies`.	false
`.sourceNetworkName`	string	The network used to make the deposit in English plain text.	false
`.depositAddress`	string	The address to which the deposit is made. This field is null for swap deposits in `PENDING_API_COMMIT` state. Info for Stellar Network Deposits Includes the memo and memo type in the following format: `{memo}:{memoType}@{stellarAccount}`	true
`.sourceAmountRequired`	string	The amount required to complete the deposit. For `DIRECT` deposits Contains the string `ARBITRARY_AMOUNT` indicating that any arbitrary amount within the upper and lower bound specified in `sourceAmountMin` and `sourceAmountMin` is acceptable. For `SWAP` deposits Contains the payment amount required to convert the source asset into the target asset you want to be credited in. Please send this exact amount. If the received source amount deviates from the value given here, then you will be credited in the source asset instead.	false
`.sourceAmountReceived`	string	A numeric string indicating the total amount received for this deposit.	false
`.sourceAmountMin`	string	A numeric string indicating the minimum amount required during arbitrary `DIRECT` deposits or the exact payment amount required during `SWAP` deposits. Is set to null of no minimum payment amount is required.	true
`.sourceAmountMax`	string	A numeric string indicating the maximum amount permitted during arbitrary `DIRECT` deposits or the exact payment amount required during `SWAP` deposits. Is set to null of no upper bound exists.	false
`.sourceAssetIssuer`	string	A string indicating the source asset issuer used during the deposit.	false
`.creditAssetIssuer`	string	A string indicating the asset your account is credited in when the deposit is complete.	false
`.creditAmountGross`	string	A numeric string indicating the gross amount your account is credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet (e.g. during arbitrary direct deposits while the deposit is awaiting payment).	true
`.creditAmountFee`	string	A numeric string indicating the processing fee collected by COINQVEST or third parties during the deposit. Is set to null when the credit amount has not been calculated yet.	true
`.creditAmountNet`	string	A numeric string indicating the exact amount you are credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet.	true
`.creditAmountNetReceived`	string	A numeric string indicating the exact amount your account was credited in. Contains the same amount as `creditAmountNet` when the deposit is complete, or 0 otherwise.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this deposit.	false
`.type`	string	The type of blockchain transaction. Can be either `DEPOSIT_ORIGIN` (blockchain payment transaction initiated by the sender, `DEPOSIT_TRANSFER` (asset issuer fund transfer from native blockchain to Stellar Network), `DEPOSIT_CONVERSION` (atomic currency swap on the Stellar Network), or `DEPOSIT_SETTLEMENT` (Stellar transaction crediting your COINQVEST merchant account).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.blockchain`	string	The blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.blockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.customerId`	string(12)	References the related customer, if any.	true
`.meta`	string	An arbitrary object containing external context information submitted by you when the deposit was created.	true
`.failover`	boolean	Indicates that a problem with the deposit referenced in `failoverParentId` occurred and an automatic failover mitigation was executed. A failover on a `SWAP` deposit credits you in the source currency and omits the currency conversion.	false
`.failoverType`	string	Indicates what kind of problem occurred and what failover mitigation was executed. Valid values are: `ALREADY_CREDITED`, `SOURCE_ASSET_MISMATCH`, `SOURCE_AMOUNT_MISMATCH`, `INTERNAL_ERROR`, `EXCHANGE_RATE_EXPIRED`, `SWAP_ALREADY_IN_PROGRESS`.	true
`.failoverParentId`	string(12)	References the original deposit on which the failover was executed. If given, you should use this id to match against your internal database records (instead of the `id` attribute).	true
`.webhook`	string	The webhook URL on your server to which COINQVEST posts callback notifications during events related to this deposit (as specified in webhook concepts).	true

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/swap-depositprotected

This endpoint invokes a cross-currency swap deposit. It enables you to send an asset (like native Bitcoin) and get credited in a different asset instead. Deposits aren't associated with a checkout process or invoice and can be used to fund your account by yourself or a customer.

Creating a swap deposit is a two-step process. In the first step, you submit the source amount and asset you are going to send as well as the desired target asset you want to be credited in. You receive a target amount, exchange rate, and deposit id in response. In the second step, you analyze the exchange rate and submit another request to POST /swap-deposit/commit to confirm acceptance and receive a deposit address in response.

Deposit objects are not re-usable. You should create new deposit requests for each intended deposit transaction.

Request

curl -X POST https://www.coinqvest.com/api/v1/swap-deposit \
     -d "@payload.json"

Where payload.json is a JSON object.

Example Payload 1 (Send EURT, receive BTC)

{
   "sourceNetworkCode":"XLM",
   "sourceAssetIssuer":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
   "sourceAmount":100,
   "targetNetworkCode":"BTC"
}

Example Payload 2 (Send native BTC, receive EURT on Stellar Network)

{
   "sourceNetworkCode":"BTC",
   "sourceAmount":0.1,
   "targetNetworkCode":"XLM",
   "targetAssetIssuer":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S"
}

Request Params (POST)

Key	Type	Description	Nullable	Mandatory
`sourceNetworkCode`	string	Specifies the network you are going to use to make the deposit. Can be a blockchain asset code as given by `GET /blockchains` or fiat currency asset code as given by `GET /fiat-currencies`. Examples Use `BTC` to make a deposit using native Bitcoin Use `EUR` to make a fiat deposit in EUR (SEPA) Use `XLM` to make a deposit in any supported asset on the Stellar Network. Specify the sending asset by setting the `sourceAssetIssuer` parameter (see below).	false	mandatory
`sourceAssetIssuer`	string	Optionally specifies the issuer of the asset you are going to send. Use an identifier as given by `GET /asset-issuers`. If no asset issuer is specified then the platform default for the selected network is used. We recommend to leave this field empty for deposits other than via the Stellar Network. Examples To send Euro tokens on the Stellar Network, set the `sourceNetworkCode` to `XLM` and use `EURT:GAP5L...OOS2S`. To send Lumens on the Stellar Network, do not provide this parameter (the platform default for the Stellar Network already is XLM) or set it to `XLM:NATIVE` explicitly. To enforce a specific anchor for your Bitcoin, Ethereum, Litecoin, or fiat deposit, please use the anchor's asset issuer id as given by `GET /asset-issuers` (advanced).	true	optional
`.sourceAmount`	numeric	Specifies the source amount you are going to send.	false	mandatory
`targetNetworkCode`	string	Specifies the network you want to be credited on when the deposit completes. Can be a blockchain asset code as given by `GET /blockchains` or fiat currency asset code as given by `GET /fiat-currencies`. Examples Use `BTC` to get credited in Bitcoin. Use `EUR` to get credited in Euro fiat tokens (on the Stellar Network). Use `XLM` to get credited in any supported asset on the Stellar Network. Specify the credit asset by setting the `targetAssetIssuer` parameter (see below).	false	mandatory
`targetAssetIssuer`	string	Optionally specifies the issuer of the asset you are going to be credited in. Use an identifier as given by `GET /asset-issuers`. If no asset issuer is specified then the platform default for the selected network is used. We recommend to leave this field empty for deposits other than via the Stellar Network. Examples To receive Euro tokens on the Stellar Network, set the `sourceNetworkCode` to `XLM` and use `EURT:GAP5L...OOS2S`. To receive Lumens on the Stellar Network, do not provide this parameter (the platform default for the Stellar Network already is XLM) or set it to `XLM:NATIVE` explicitly. To enforce a specific asset issuer for your Bitcoin, Ethereum, Litecoin, or fiat deposit, please use the anchor's asset issuer id as given by `GET /asset-issuers` (advanced).	true	optional
`.customerId`	string(12)	Specifies a customer related to this deposit, if any. Please use the identifier as given by `POST /customer`.	true	optional
`.meta`	object	A custom object containing arbitrary information that you would like to associate with this deposit, if any. This object is included in associated webhook payloads and API responses whenever this deposit is referenced.	true	optional
`.webhook`	string	A webhook URL on your server that listens for related deposit events as specified in webhook concepts.	null	optional

Success Response application/json

{
   "deposit":{
      "id":"5074f4ee055d",
      "type":"SWAP",
      "state":"PENDING_API_COMMIT",
      "origin":"API",
      "createTime":"2021-05-06T22:15:37+00:00",
      "completeTime":null,
      "expireTime":"2021-05-06T23:15:37+00:00",
      "sourceNetworkCode":"BTC",
      "sourceNetworkName":"Bitcoin",
      "depositAddress":null,
      "sourceAmountRequired":"0.1",
      "sourceAmountReceived":"0",
      "sourceAmountMin":"0.1",
      "sourceAmountMax":"0.1",
      "sourceAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
      "creditAssetIssuer":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
      "creditAmountGross":"5021.2837211",
      "creditAmountFee":"0",
      "creditAmountNet":"5021.2837211",
      "creditAmountNetReceived":"0",
      "blockchainTransactions":[],
      "customerId":null,
      "meta":null,
      "failover": false,
      "failoverType": null,
      "failoverParentId": null,
      "webhook":"https://www.your-server.com/path/to/webhook"
   }
}

Success Response Attributes

Name	Type	Description	Nullable
`.deposit{}`	object	An object with deposit information.	false
`.id`	string(12)	Unique identifier of this deposit.	false
`.type`	string	The deposit type. Either `DIRECT` for direct deposits without currency conversion or `SWAP` for deposits involving a currency swap.	false
`.state`	string	The deposit state. The list of possible values is `COMPLETED` , `AWAITING_DEPOSIT`, `PROCESSING`, `PENDING_API_COMMIT` and `FAILED`.	false
`.origin`	string	Indicates how the deposit was initiated, either `UI` or `API`.	false
`.createTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was created.	false
`.completeTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was completed. This value is set when the deposit state is `COMPLETED` and otherwise it is null.	true
`.expireTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. This value only set for deposits of type `SWAP` and otherwise it is null. Please make deposit before the expiration time to ensure currency conversion. If the deposit is made after the expiration time, you might be credited in the source currency instead.	true
`.sourceNetworkCode`	string(3)	Specifies the network used to make the deposit. Can be a blockchain asset code as given by `GET /blockchains` or fiat currency asset code as given by `GET /fiat-currencies`.	false
`.sourceNetworkName`	string	The network used to make the deposit in English plain text.	false
`.depositAddress`	string	The address to which the deposit is made. This field is null for swap deposits in `PENDING_API_COMMIT` state. Info for Stellar Network Deposits Includes the memo and memo type in the following format: `{memo}:{memoType}@{stellarAccount}`	true
`.sourceAmountRequired`	string	The amount required to complete the deposit. For `DIRECT` deposits Contains the string `ARBITRARY_AMOUNT` indicating that any arbitrary amount within the upper and lower bound specified in `sourceAmountMin` and `sourceAmountMin` is acceptable. For `SWAP` deposits Contains the payment amount required to convert the source asset into the target asset you want to be credited in. Please send this exact amount. If the received source amount deviates from the value given here, then you will be credited in the source asset instead.	false
`.sourceAmountReceived`	string	A numeric string indicating the total amount received for this deposit.	false
`.sourceAmountMin`	string	A numeric string indicating the minimum amount required during arbitrary `DIRECT` deposits or the exact payment amount required during `SWAP` deposits. Is set to null of no minimum payment amount is required.	true
`.sourceAmountMax`	string	A numeric string indicating the maximum amount permitted during arbitrary `DIRECT` deposits or the exact payment amount required during `SWAP` deposits. Is set to null of no upper bound exists.	false
`.sourceAssetIssuer`	string	A string indicating the source asset issuer used during the deposit.	false
`.creditAssetIssuer`	string	A string indicating the asset your account is credited in when the deposit is complete.	false
`.creditAmountGross`	string	A numeric string indicating the gross amount your account is credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet (e.g. during arbitrary direct deposits while the deposit is awaiting payment).	true
`.creditAmountFee`	string	A numeric string indicating the processing fee collected by COINQVEST or third parties during the deposit. Is set to null when the credit amount has not been calculated yet.	true
`.creditAmountNet`	string	A numeric string indicating the exact amount you are credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet.	true
`.creditAmountNetReceived`	string	A numeric string indicating the exact amount your account was credited in. Contains the same amount as `creditAmountNet` when the deposit is complete, or 0 otherwise.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this deposit.	false
`.type`	string	The type of blockchain transaction. Can be either `DEPOSIT_ORIGIN` (blockchain payment transaction initiated by the sender, `DEPOSIT_TRANSFER` (asset issuer fund transfer from native blockchain to Stellar Network), `DEPOSIT_CONVERSION` (atomic currency swap on the Stellar Network), or `DEPOSIT_SETTLEMENT` (Stellar transaction crediting your COINQVEST merchant account).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.blockchain`	string	The blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.blockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.customerId`	string(12)	References the related customer, if any.	true
`.meta`	string	An arbitrary object containing external context information submitted by you when the deposit was created.	true
`.failover`	boolean	Indicates that a problem with the deposit referenced in `failoverParentId` occurred and an automatic failover mitigation was executed. A failover on a `SWAP` deposit credits you in the source currency and omits the currency conversion.	false
`.failoverType`	string	Indicates what kind of problem occurred and what failover mitigation was executed. Valid values are: `ALREADY_CREDITED`, `SOURCE_ASSET_MISMATCH`, `SOURCE_AMOUNT_MISMATCH`, `INTERNAL_ERROR`, `EXCHANGE_RATE_EXPIRED`, `SWAP_ALREADY_IN_PROGRESS`.	true
`.failoverParentId`	string(12)	References the original deposit on which the failover was executed. If given, you should use this id to match against your internal database records (instead of the `id` attribute).	true
`.webhook`	string	The webhook URL on your server to which COINQVEST posts callback notifications during events related to this deposit (as specified in webhook concepts).	true

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/swap-deposit/commitprotected

This endpoint takes a depositId parameter as given by POST /swap-deposit. Upon successful completion, the deposit request is committed and processed by COINQVEST. Its state changes from PENDING_API_COMMIT to AWAITING_DEPOSIT and a deposit address is given.

In the previous step, POST /swap-deposit gave you an object like this:

Example Response (as given by `POST /swap-deposit`)

{
   "deposit":{
      "id":"5074f4ee055d",
      "type":"SWAP",
      "state":"PENDING_API_COMMIT",
      "origin":"API",
      "createTime":"2021-05-06T22:15:37+00:00",
      "completeTime":null,
      "expireTime":"2021-05-06T23:15:37+00:00",
      "sourceNetworkCode":"BTC",
      "sourceNetworkName":"Bitcoin",
      "depositAddress":null,
      "sourceAmountRequired":"0.1",
      "sourceAmountReceived":"0",
      "sourceAmountMin":"0.1",
      "sourceAmountMax":"0.1",
      "sourceAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
      "creditAssetIssuer":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
      "creditAmountGross":"5021.2837211",
      "creditAmountFee":"0",
      "creditAmountNet":"5021.2837211",
      "creditAmountNetReceived":"0",
      "blockchainTransactions":[],
      "customerId":null,
      "meta":null,
      "failover": false,
      "failoverType": null,
      "failoverParentId": null,
      "webhook":"https://www.your-server.com/path/to/webhook"
   }
}

As a prerequisite to invoke this endpoint, you should have received a response as above from POST /swap-deposit. Its state is PENDING_API_COMMIT, which means that the deposit is awaiting final confirmation through this endpoint. Upon inspection and acceptance of the given creditAmountNet, you need to invoke POST /swap-deposit/commit (this endpoint) to confirm the target amount and receive a deposit address.

Request

curl -X POST 'https://www.coinqvest.com/api/v1/swap-deposit/commit'
    -d "@payload.json"

Where payload.json is a JSON object.

Example Payload

{
  "depositId":"12d72c3c8145"
}

Request Params

Key	Type	Description	Default	Mandatory
`depositId`	string(12)	Unique identifier as given by `POST /swap-deposit`.	null	mandatory

Success Response application/json

{
   "deposit":{
      "id":"5074f4ee055d",
      "type":"SWAP",
      "state":"AWAITING_DEPOSIT",
      "origin":"API",
      "createTime":"2021-05-06T22:15:37+00:00",
      "completeTime":null,
      "expireTime":"2021-05-06T23:15:37+00:00",
      "sourceNetworkCode":"BTC",
      "sourceNetworkName":"Bitcoin",
      "depositAddress":"bc1q9wlypnrpxtaynswkl2culgz2l6ffsd2xwu5zdlfc7dfxd5lsaxpqw3akmf",
      "sourceAmountRequired":"0.1",
      "sourceAmountReceived":"0",
      "sourceAmountMin":"0.1",
      "sourceAmountMax":"0.1",
      "sourceAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
      "creditAssetIssuer":"EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
      "creditAmountGross":"5021.2837211",
      "creditAmountFee":"0",
      "creditAmountNet":"5021.2837211",
      "creditAmountNetReceived":"0",
      "blockchainTransactions":[],
      "customerId":null,
      "meta":null,
      "failover": false,
      "failoverType": null,
      "failoverParentId": null,
      "webhook":"https://www.your-server.com/path/to/webhook"
   }
}

Success Response Attributes

Name	Type	Description	Nullable
`.deposit{}`	object	An object containing deposit information.	false
`.id`	string(12)	Unique identifier of this deposit.	false
`.type`	string	The deposit type. Either `DIRECT` for direct deposits without currency conversion or `SWAP` for deposits involving a currency swap.	false
`.state`	string	The deposit state. The list of possible values is `COMPLETED` , `AWAITING_DEPOSIT`, `PROCESSING`, `PENDING_API_COMMIT` and `FAILED`.	false
`.origin`	string	Indicates how the deposit was initiated, either `UI` or `API`.	false
`.createTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was created.	false
`.completeTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was completed. This value is set when the deposit state is `COMPLETED` and otherwise it is null.	true
`.expireTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. This value only set for deposits of type `SWAP` and otherwise it is null. Please make deposit before the expiration time to ensure currency conversion. If the deposit is made after the expiration time, you might be credited in the source currency instead.	true
`.sourceNetworkCode`	string(3)	Specifies the network used to make the deposit. Can be a blockchain asset code as given by `GET /blockchains` or fiat currency asset code as given by `GET /fiat-currencies`.	false
`.sourceNetworkName`	string	The network used to make the deposit in English plain text.	false
`.depositAddress`	string	The address to which the deposit is made. This field is null for swap deposits in `PENDING_API_COMMIT` state. Info for Stellar Network Deposits Includes the memo and memo type in the following format: `{memo}:{memoType}@{stellarAccount}`	true
`.sourceAmountRequired`	string	The amount required to complete the deposit. For `DIRECT` deposits Contains the string `ARBITRARY_AMOUNT` indicating that any arbitrary amount within the upper and lower bound specified in `sourceAmountMin` and `sourceAmountMin` is acceptable. For `SWAP` deposits Contains the payment amount required to convert the source asset into the target asset you want to be credited in. Please send this exact amount. If the received source amount deviates from the value given here, then you will be credited in the source asset instead.	false
`.sourceAmountReceived`	string	A numeric string indicating the total amount received for this deposit.	false
`.sourceAmountMin`	string	A numeric string indicating the minimum amount required during arbitrary `DIRECT` deposits or the exact payment amount required during `SWAP` deposits. Is set to null of no minimum payment amount is required.	true
`.sourceAmountMax`	string	A numeric string indicating the maximum amount permitted during arbitrary `DIRECT` deposits or the exact payment amount required during `SWAP` deposits. Is set to null of no upper bound exists.	false
`.sourceAssetIssuer`	string	A string indicating the source asset issuer used during the deposit.	false
`.creditAssetIssuer`	string	A string indicating the asset your account is credited in when the deposit is complete.	false
`.creditAmountGross`	string	A numeric string indicating the gross amount your account is credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet (e.g. during arbitrary direct deposits while the deposit is awaiting payment).	true
`.creditAmountFee`	string	A numeric string indicating the processing fee collected by COINQVEST or third parties during the deposit. Is set to null when the credit amount has not been calculated yet.	true
`.creditAmountNet`	string	A numeric string indicating the exact amount you are credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet.	true
`.creditAmountNetReceived`	string	A numeric string indicating the exact amount your account was credited in. Contains the same amount as `creditAmountNet` when the deposit is complete, or 0 otherwise.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this deposit.	false
`.type`	string	The type of blockchain transaction. Can be either `DEPOSIT_ORIGIN` (blockchain payment transaction initiated by the sender, `DEPOSIT_TRANSFER` (asset issuer fund transfer from native blockchain to Stellar Network), `DEPOSIT_CONVERSION` (atomic currency swap on the Stellar Network), or `DEPOSIT_SETTLEMENT` (Stellar transaction crediting your COINQVEST merchant account).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.blockchain`	string	The blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.blockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.customerId`	string(12)	References the related customer, if any.	true
`.meta`	string	An arbitrary object containing external context information submitted by you when the deposit was created.	true
`.failover`	boolean	Indicates that a problem with the deposit referenced in `failoverParentId` occurred and an automatic failover mitigation was executed. A failover on a `SWAP` deposit credits you in the source currency and omits the currency conversion.	false
`.failoverType`	string	Indicates what kind of problem occurred and what failover mitigation was executed. Valid values are: `ALREADY_CREDITED`, `SOURCE_ASSET_MISMATCH`, `SOURCE_AMOUNT_MISMATCH`, `INTERNAL_ERROR`, `EXCHANGE_RATE_EXPIRED`, `SWAP_ALREADY_IN_PROGRESS`.	true
`.failoverParentId`	string(12)	References the original deposit on which the failover was executed. If given, you should use this id to match against your internal database records (instead of the `id` attribute).	true
`.webhook`	string	The webhook URL on your server to which COINQVEST posts callback notifications during events related to this deposit (as specified in webhook concepts).	true

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/depositprotected

Retrieves details of a given deposit.

Request

curl 'https://www.coinqvest.com/api/v1/deposit?id=xxx'

Request Params

Key	Type	Description	Default	Mandatory
`id`	string(12)	Unique identifier as given by `GET /deposits` or `POST /deposit` or `POST /swap-deposit`.	null	mandatory

Success Response application/json

{
   "deposit":{
      "id":"262785ce7dc1",
      "type":"SWAP",
      "state":"COMPLETED",
      "origin":"API",
      "createTime":"2021-05-14T15:53:14+00:00",
      "completeTime":"2021-05-14T15:56:15+00:00",
      "expireTime":"2021-05-14T16:53:14+00:00",
      "sourceNetworkCode":"LTC",
      "sourceNetworkName":"Litecoin",
      "depositAddress":"MUhBPBgjngzREm1NJfK3pUMTYSBDTx3v7X",
      "sourceAmountRequired":"0.1",
      "sourceAmountReceived":"0.1",
      "sourceAmountMin":"0.1",
      "sourceAmountMax":"0.1",
      "sourceAssetIssuer":"LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP",
      "creditAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "creditAmountGross":"32.2564553",
      "creditAmountFee":"0.3282536",
      "creditAmountNet":"31.9282017",
      "creditAmountNetReceived":"31.9282017",
      "blockchainTransactions":[
         {
            "type":"DEPOSIT_ORIGIN",
            "typeDescription":"Blockchain payment transaction initiated by customer.",
            "blockchain":"Litecoin",
            "blockchainAssetCode":"LTC",
            "tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7eeaab614a7",
            "amount":"0.1000000",
            "amountAssetCode":"LTC"
         },
         {
            "type":"DEPOSIT_TRANSFER",
            "typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
            "blockchain":"Stellar Network",
            "blockchainAssetCode":"XLM",
            "tx":"5486e7e200acfb0a4dc1150e432ab9f716aa13b5982e08af78802a701e4d60c8",
            "amount":"0.1000000",
            "amountAssetCode":"LTC"
         },
         {
            "type":"DEPOSIT_CONVERSION",
            "typeDescription":"COINQVEST transaction converting source funds to target asset.",
            "blockchain":"Stellar Network",
            "blockchainAssetCode":"XLM",
            "tx":"2067ee5ddac84537596a35bfcea92f95ce5fe1e64d56f0435430775165c584a7",
            "amount":"0.1000000",
            "amountAssetCode":"LTC"
         },
         {
            "type":"DEPOSIT_SETTLEMENT",
            "typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
            "blockchain":"Stellar Network",
            "blockchainAssetCode":"XLM",
            "tx":"5a8c6de913a5675d3a5b35890a5938c9b2a3f78ca6f1d61b3f67190bab955797",
            "amount":"32.2564553",
            "amountAssetCode":"USDC"
         }
      ],
      "customerId":"3b25c712a52e",
      "meta":{
         "external_id":"df2ae36472ac"
      },
      "failover":false,
      "failoverType":null,
      "failoverParentId":null,
      "webhook":"https://www.your-server.com/path/to/webhook"
   }
}

Success Response Attributes

Name	Type	Description	Nullable
`.deposit{}`	object	An object containing deposit information.	false
`.id`	string(12)	Unique identifier of this deposit.	false
`.type`	string	The deposit type. Either `DIRECT` for direct deposits without currency conversion or `SWAP` for deposits involving a currency swap.	false
`.state`	string	The deposit state. The list of possible values is `COMPLETED` , `AWAITING_DEPOSIT`, `PROCESSING`, `PENDING_API_COMMIT` and `FAILED`.	false
`.origin`	string	Indicates how the deposit was initiated, either `UI` or `API`.	false
`.createTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was created.	false
`.completeTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was completed. This value is set when the deposit state is `COMPLETED` and otherwise it is null.	true
`.expireTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. This value only set for deposits of type `SWAP` and otherwise it is null. Please make deposit before the expiration time to ensure currency conversion. If the deposit is made after the expiration time, you might be credited in the source currency instead.	true
`.sourceNetworkCode`	string(3)	Specifies the network used to make the deposit. Can be a blockchain asset code as given by `GET /blockchains` or fiat currency asset code as given by `GET /fiat-currencies`.	false
`.sourceNetworkName`	string	The network used to make the deposit in English plain text.	false
`.depositAddress`	string	The address to which the deposit is made. This field is null for swap deposits in `PENDING_API_COMMIT` state. Info for Stellar Network Deposits Includes the memo and memo type in the following format: `{memo}:{memoType}@{stellarAccount}`	true
`.sourceAmountRequired`	string	The amount required to complete the deposit. For `DIRECT` deposits Contains the string `ARBITRARY_AMOUNT` indicating that any arbitrary amount within the upper and lower bound specified in `sourceAmountMin` and `sourceAmountMin` is acceptable. For `SWAP` deposits Contains the payment amount required to convert the source asset into the target asset you want to be credited in. Please send this exact amount. If the received source amount deviates from the value given here, then you will be credited in the source asset instead.	false
`.sourceAmountReceived`	string	A numeric string indicating the total amount received for this deposit.	false
`.sourceAmountMin`	string	A numeric string indicating the minimum amount required during arbitrary `DIRECT` deposits or the exact payment amount required during `SWAP` deposits. Is set to null of no minimum payment amount is required.	true
`.sourceAmountMax`	string	A numeric string indicating the maximum amount permitted during arbitrary `DIRECT` deposits or the exact payment amount required during `SWAP` deposits. Is set to null of no upper bound exists.	false
`.sourceAssetIssuer`	string	A string indicating the source asset issuer used during the deposit.	false
`.creditAssetIssuer`	string	A string indicating the asset your account is credited in when the deposit is complete.	false
`.creditAmountGross`	string	A numeric string indicating the gross amount your account is credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet (e.g. during arbitrary direct deposits while the deposit is awaiting payment).	true
`.creditAmountFee`	string	A numeric string indicating the processing fee collected by COINQVEST or third parties during the deposit. Is set to null when the credit amount has not been calculated yet.	true
`.creditAmountNet`	string	A numeric string indicating the exact amount you are credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet.	true
`.creditAmountNetReceived`	string	A numeric string indicating the exact amount your account was credited in. Contains the same amount as `creditAmountNet` when the deposit is complete, or 0 otherwise.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this deposit.	false
`.type`	string	The type of blockchain transaction. Can be either `DEPOSIT_ORIGIN` (blockchain payment transaction initiated by the sender, `DEPOSIT_TRANSFER` (asset issuer fund transfer from native blockchain to Stellar Network), `DEPOSIT_CONVERSION` (atomic currency swap on the Stellar Network), or `DEPOSIT_SETTLEMENT` (Stellar transaction crediting your COINQVEST merchant account).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.blockchain`	string	The blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.blockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.customerId`	string(12)	References the related customer, if any.	true
`.meta`	string	An arbitrary object containing external context information submitted by you when the deposit was created.	true
`.failover`	boolean	Indicates that a problem with the deposit referenced in `failoverParentId` occurred and an automatic failover mitigation was executed. A failover on a `SWAP` deposit credits you in the source currency and omits the currency conversion.	false
`.failoverType`	string	Indicates what kind of problem occurred and what failover mitigation was executed. Valid values are: `ALREADY_CREDITED`, `SOURCE_ASSET_MISMATCH`, `SOURCE_AMOUNT_MISMATCH`, `INTERNAL_ERROR`, `EXCHANGE_RATE_EXPIRED`, `SWAP_ALREADY_IN_PROGRESS`.	true
`.failoverParentId`	string(12)	References the original deposit on which the failover was executed. If given, you should use this id to match against your internal database records (instead of the `id` attribute).	true
`.webhook`	string	The webhook URL on your server to which COINQVEST posts callback notifications during events related to this deposit (as specified in webhook concepts).	true

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/depositsprotected

Retrieves a list of your deposits (in descending order from newest to oldest).

Request

curl 'https://www.coinqvest.com/api/v1/deposits?limit=250&offset=0'

Request Params

Key	Type	Description	Default	Mandatory
`limit`	integer	Maximum number of deposit objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Success Response application/json

{
   "count":2,
   "limit":10,
   "offset":0,
   "deposits":[
      {
         "deposit":{
            "id":"5074f4ee055d",
            "type":"DIRECT",
            "state":"AWAITING_DEPOSIT",
            "origin":"API",
            "createTime":"2021-05-06T22:15:37+00:00",
            "completeTime":null,
            "expireTime":null,
            "sourceNetworkCode":"BTC",
            "sourceNetworkName":"Bitcoin",
            "depositAddress":"bc1q9wlypnrpxtaynswkl2culgz2l6ffsd2xwu5zdlfc7dfxd5lsaxpqw3akmf",
            "sourceAmountRequired":"ARBITRARY_AMOUNT",
            "sourceAmountReceived":"0",
            "sourceAmountMin":"0.0002",
            "sourceAmountMax":null,
            "sourceAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
            "creditAssetIssuer":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
            "creditAmountGross":null,
            "creditAmountFee":null,
            "creditAmountNet":null,
            "creditAmountNetReceived":"0",
            "blockchainTransactions":[],
            "customerId":null,
            "meta":null,
            "failover": false,
            "failoverType": null,
            "failoverParentId": null,
            "webhook":"https://www.your-server.com/path/to/webhook"
         }
      },
      {
         "id":"262785ce7dc1",
         "type":"SWAP",
         "state":"COMPLETED",
         "origin":"API",
         "createTime":"2021-05-14T15:53:14+00:00",
         "completeTime":"2021-05-14T15:56:15+00:00",
         "expireTime":"2021-05-14T16:53:14+00:00",
         "sourceNetworkCode":"LTC",
         "sourceNetworkName":"Litecoin",
         "depositAddress":"MUhBPBgjngzREm1NJfK3pUMTYSBDTx3v7X",
         "sourceAmountRequired":"0.1",
         "sourceAmountReceived":"0.1",
         "sourceAmountMin":"0.1",
         "sourceAmountMax":"0.1",
         "sourceAssetIssuer":"LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP",
         "creditAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "creditAmountGross":"32.2564553",
         "creditAmountFee":"0.3282536",
         "creditAmountNet":"31.9282017",
         "creditAmountNetReceived":"31.9282017",
         "blockchainTransactions":[
            {
               "type":"DEPOSIT_ORIGIN",
               "typeDescription":"Blockchain payment transaction initiated by customer.",
               "blockchain":"Litecoin",
               "blockchainAssetCode":"LTC",
               "tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7eeaab614a7",
               "amount":"0.1000000",
               "amountAssetCode":"LTC"
            },
            {
               "type":"DEPOSIT_TRANSFER",
               "typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
               "blockchain":"Stellar Network",
               "blockchainAssetCode":"XLM",
               "tx":"5486e7e200acfb0a4dc1150e432ab9f716aa13b5982e08af78802a701e4d60c8",
               "amount":"0.1000000",
               "amountAssetCode":"LTC"
            },
            {
               "type":"DEPOSIT_CONVERSION",
               "typeDescription":"COINQVEST transaction converting source funds to target asset.",
               "blockchain":"Stellar Network",
               "blockchainAssetCode":"XLM",
               "tx":"2067ee5ddac84537596a35bfcea92f95ce5fe1e64d56f0435430775165c584a7",
               "amount":"0.1000000",
               "amountAssetCode":"LTC"
            },
            {
               "type":"DEPOSIT_SETTLEMENT",
               "typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
               "blockchain":"Stellar Network",
               "blockchainAssetCode":"XLM",
               "tx":"5a8c6de913a5675d3a5b35890a5938c9b2a3f78ca6f1d61b3f67190bab955797",
               "amount":"32.2564553",
               "amountAssetCode":"USDC"
            }
         ],
         "customerId":"3b25c712a52e",
         "meta":{
            "external_id":"df2ae36472ac"
         },
         "failover": false,
         "failoverType": null,
         "failoverParentId": null,
         "webhook":"https://www.your-server.com/path/to/webhook"
      }
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`.count`	integer	The total number of deposits initiated in this account.	false
`.limit`	integer	The limit argument used in this request.	false
`.offset`	integer	The pagination offset used in this request.	false
`.deposits[]`	array	A list of deposit objects.	false
`.id`	string(12)	Unique identifier of this deposit.	false
`.type`	string	The deposit type. Either `DIRECT` for direct deposits without currency conversion or `SWAP` for deposits involving a currency swap.	false
`.state`	string	The deposit state. The list of possible values is `COMPLETED` , `AWAITING_DEPOSIT`, `PROCESSING`, `PENDING_API_COMMIT` and `FAILED`.	false
`.origin`	string	Indicates how the deposit was initiated, either `UI` or `API`.	false
`.createTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was created.	false
`.completeTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was completed. This value is set when the deposit state is `COMPLETED` and otherwise it is null.	true
`.expireTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. This value only set for deposits of type `SWAP` and otherwise it is null. Please make deposit before the expiration time to ensure currency conversion. If the deposit is made after the expiration time, you might be credited in the source currency instead.	true
`.sourceNetworkCode`	string(3)	Specifies the network used to make the deposit. Can be a blockchain asset code as given by `GET /blockchains` or fiat currency asset code as given by `GET /fiat-currencies`.	false
`.sourceNetworkName`	string	The network used to make the deposit in English plain text.	false
`.depositAddress`	string	The address to which the deposit is made. This field is null for swap deposits in `PENDING_API_COMMIT` state. Info for Stellar Network Deposits Includes the memo and memo type in the following format: `{memo}:{memoType}@{stellarAccount}`	true
`.sourceAmountRequired`	string	The amount required to complete the deposit. For `DIRECT` deposits Contains the string `ARBITRARY_AMOUNT` indicating that any arbitrary amount within the upper and lower bound specified in `sourceAmountMin` and `sourceAmountMin` is acceptable. For `SWAP` deposits Contains the payment amount required to convert the source asset into the target asset you want to be credited in. Please send this exact amount. If the received source amount deviates from the value given here, then you will be credited in the source asset instead.	false
`.sourceAmountReceived`	string	A numeric string indicating the total amount received for this deposit.	false
`.sourceAmountMin`	string	A numeric string indicating the minimum amount required during arbitrary `DIRECT` deposits or the exact payment amount required during `SWAP` deposits. Is set to null of no minimum payment amount is required.	true
`.sourceAmountMax`	string	A numeric string indicating the maximum amount permitted during arbitrary `DIRECT` deposits or the exact payment amount required during `SWAP` deposits. Is set to null of no upper bound exists.	false
`.sourceAssetIssuer`	string	A string indicating the source asset issuer used during the deposit.	false
`.creditAssetIssuer`	string	A string indicating the asset your account is credited in when the deposit is complete.	false
`.creditAmountGross`	string	A numeric string indicating the gross amount your account is credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet (e.g. during arbitrary direct deposits while the deposit is awaiting payment).	true
`.creditAmountFee`	string	A numeric string indicating the processing fee collected by COINQVEST or third parties during the deposit. Is set to null when the credit amount has not been calculated yet.	true
`.creditAmountNet`	string	A numeric string indicating the exact amount you are credited in when the deposit is complete. Is set to null when the credit amount has not been calculated yet.	true
`.creditAmountNetReceived`	string	A numeric string indicating the exact amount your account was credited in. Contains the same amount as `creditAmountNet` when the deposit is complete, or 0 otherwise.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this deposit.	false
`.type`	string	The type of blockchain transaction. Can be either `DEPOSIT_ORIGIN` (blockchain payment transaction initiated by the sender, `DEPOSIT_TRANSFER` (asset issuer fund transfer from native blockchain to Stellar Network), `DEPOSIT_CONVERSION` (atomic currency swap on the Stellar Network), or `DEPOSIT_SETTLEMENT` (Stellar transaction crediting your COINQVEST merchant account).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.blockchain`	string	The blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.blockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false
`.customerId`	string(12)	References the related customer, if any.	true
`.meta`	string	An arbitrary object containing external context information submitted by you when the deposit was created.	true
`.failover`	boolean	Indicates that a problem with the deposit referenced in `failoverParentId` occurred and an automatic failover mitigation was executed. A failover on a `SWAP` deposit credits you in the source currency and omits the currency conversion.	false
`.failoverType`	string	Indicates what kind of problem occurred and what failover mitigation was executed. Valid values are: `ALREADY_CREDITED`, `SOURCE_ASSET_MISMATCH`, `SOURCE_AMOUNT_MISMATCH`, `INTERNAL_ERROR`, `EXCHANGE_RATE_EXPIRED`, `SWAP_ALREADY_IN_PROGRESS`.	true
`.failoverParentId`	string(12)	References the original deposit on which the failover was executed. If given, you should use this id to match against your internal database records (instead of the `id` attribute).	true
`.webhook`	string	The webhook URL on your server to which COINQVEST posts callback notifications during events related to this deposit (as specified in webhook concepts).	true

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/swapprotected

This endpoint invokes an asset swap and converts one of your assets in COINQVEST into another asset.

Invoking a swap a two-step process. In the first step, you specify the source asset you are going to send as well as the desired target asset you want to be credited in. Alongside, you can either specify the source amount you are willing to send or the target amount you wish to receive.

In the second step, you analyze the exchange rate in the response and submit another request to POST /swap/commit to confirm acceptance and execute the swap.

Request

curl -X POST https://www.coinqvest.com/api/v1/swap \
     -d "@payload.json"

Where payload.json is a JSON object.

Example Payload 1 (Swap 100 USD into BTC)

{
   "sourceAsset":"USD",
   "sourceAmount":100,
   "targetAsset":"BTC"
}

Above example requests a swap from of 100 USD into Bitcoin. The API response contains the amount of BTC that will be credited to your account in exchange for 100 USD. Confirm the exchange rate by invoking POST /swap/commit.

Example Payload 2 (Swap BTC into 100 XLM)

{
   "sourceAsset":"BTC",
   "targetAsset":"XLM",
   "targetAmount":100
}

Above example requests a swap from BTC into 100 XLM. The API response contains the amount of BTC that will be debited from your account in exchange for 100 XLM. Confirm the exchange rate by invoking POST /swap/commit.

Request Params (POST)

Key	Type	Description	Nullable	Mandatory
`sourceAsset`	string	Specifies the asset debited from your account. Can be a blockchain asset code as given by `GET /blockchains` or fiat currency asset code as given by `GET /fiat-currencies`. Use an asset id as given by `GET /wallets` to explicitly specify a select source asset.	false	mandatory
`sourceAmount`	numeric	Specifies the amount of `sourceAsset` you wish to debit from your account to make the swap. The API response contains the calculated target amount, which you can inspect and confirm by invoking a subsequent request to `POST /swap/commit`. If you would like to specify the exact target amount instead, please use the `targetAmount` attribute and don't specify a `sourceAmount`.	true	optional
`targetAsset`	string	Specifies the asset credited to your account when the swap completes. Can be a blockchain asset code as given by `GET /blockchains` or fiat currency asset code as given by `GET /fiat-currencies`. Use an asset id as given by `GET /wallets` to explicitly specify a select target asset.	false	mandatory
`targetAmount`	numeric	Specifies the amount of `targetAsset` you wish to credit to your account when the swap completes. The API response contains the required source amount, which you can inspect and confirm by invoking a subsequent request to `POST /swap/commit`. If you would like to specify the exact source amount instead, please use the `sourceAmount` attribute and don't specify a `targetAmount`.	true	optional

Success Response application/json

{
   "swap":{
      "id":"5074f4ee055d",
      "state":"PENDING_API_COMMIT",
      "type":"SOURCE_SPECIFIED",
      "origin":"API",
      "createTime":"2021-05-06T22:15:37+00:00",
      "completeTime":null,
      "expireTime":"2021-05-06T23:15:37+00:00",
      "sourceAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "sourceAmount":"100.0000000",
      "targetAssetIssuer":"XLM:NATIVE",
      "targetAmount":"243.3928192",
      "blockchainTransactions":[]
   }
}

Success Response Attributes

Name	Type	Description	Nullable
`.swap{}`	object	An object with swap information.	false
`.id`	string(12)	Unique identifier of this swap.	false
`.state`	string	The swap state. The list of possible values is `COMPLETED` , `PENDING_API_COMMIT`, `PROCESSING`, and `FAILED`.	false
`.type`	string	The swap type. `SOURCE_SPECIFIED` indicates that you specified the source amount. `TARGET_SPECIFIED` indicates that you specified the target amount.	false
`.origin`	string	Indicates how the swap was initiated, either `UI` or `API`.	false
`.createTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was created.	false
`.completeTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was completed. This value is set when the swap state is `COMPLETED` and otherwise it is null.	true
`.expireTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. Please send the API commit before the expiration time to ensure swap execution.	true
`.sourceAsset`	string	Indicates the asset debited from your account on swap completion. Matches an asset id as given by `GET /wallets`.	false
`.sourceAmount`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account on swap completion.	false
`.targetAsset`	string	Indicates the asset credited to your account on swap completion. Matches an asset id as given by `GET /wallets`.	false
`.targetAmount`	string	A numeric string indicating the total amount of `targetAsset` credited to your account on swap completion.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this swap.	false
`.type`	string	The type of blockchain transaction. This is always set to `SWAP` (blockchain transaction executing the currency swap).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.blockchain`	string	The blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.blockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/swap/commitprotected

This endpoint takes a swapId parameter as given by POST /swap. Upon successful completion, the swap request is committed and processed by COINQVEST. Its state changes from PENDING_API_COMMIT to AWAITING_DEPOSIT and your account is debited the source amount and asset and credited the target amount and asset.

Important: Please note that this endpoint requires a long timeout setting (we recommend 120 seconds) as it waits for blockchain confirmation before returning a response.

In the previous step, POST /swap gave you an object like this:

Example Response (as given by `POST /swap`)

{
   "swap":{
      "id":"5074f4ee055d",
      "state":"PENDING_API_COMMIT",
      "type":"SOURCE_SPECIFIED",
      "origin":"API",
      "createTime":"2021-05-06T22:15:37+00:00",
      "completeTime":null,
      "expireTime":"2021-05-06T23:15:37+00:00",
      "sourceAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "sourceAmount":"100.0000000",
      "targetAssetIssuer":"XLM:NATIVE",
      "targetAmount":"243.3928192",
      "blockchainTransactions":[]
   }
}

As a prerequisite to invoke this endpoint, you should have received a response as above from POST /swap. Its state is PENDING_API_COMMIT, which means that the deposit is awaiting final confirmation through this endpoint. Upon inspection and acceptance of the given source and target amounts, you need to invoke POST /swap-deposit/commit (this endpoint) to execute the swap.

Request

curl -X POST 'https://www.coinqvest.com/api/v1/swap/commit'
    -d "@payload.json"

Where payload.json is a JSON object.

Example Payload

{
  "swapId":"12d72c3c8145"
}

Request Params

Key	Type	Description	Default	Mandatory
`swapId`	string(12)	Unique identifier as given by `POST /swap`.	null	mandatory

Success Response application/json

{
   "swap":{
      "id":"5074f4ee055d",
      "state":"COMPLETED",
      "type":"SOURCE_SPECIFIED",
      "origin":"API",
      "createTime":"2021-05-06T22:15:37+00:00",
      "completeTime":"2021-05-06T22:16:01+00:00",
      "expireTime":"2021-05-06T23:15:37+00:00",
      "sourceAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "sourceAmount":"100.0000000",
      "targetAssetIssuer":"XLM:NATIVE",
      "targetAmount":"243.3928192",
      "blockchainTransactions":[
        {
           "type":"SWAP",
           "typeDescription":"Blockchain transaction executed during the swap on the Stellar Network.",
           "blockchain":"Stellar Network",
           "blockchainAssetCode":"XLM",
           "tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7efaab614a7",
           "amount":"243.3928192",
           "amountAssetCode":"XLM"
        }
      ]
   }
}

Success Response Attributes

Name	Type	Description	Nullable
`.swap{}`	object	An object containing swap information.	false
`.id`	string(12)	Unique identifier of this swap.	false
`.state`	string	The swap state. The list of possible values is `COMPLETED` , `PENDING_API_COMMIT`, `PROCESSING`, and `FAILED`.	false
`.type`	string	The swap type. `SOURCE_SPECIFIED` indicates that you specified the source amount. `TARGET_SPECIFIED` indicates that you specified the target amount.	false
`.origin`	string	Indicates how the swap was initiated, either `UI` or `API`.	false
`.createTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was created.	false
`.completeTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was completed. This value is set when the swap state is `COMPLETED` and otherwise it is null.	true
`.expireTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. Please send the API commit before the expiration time to ensure swap execution.	true
`.sourceAsset`	string	Indicates the asset debited from your account on swap completion. Matches an asset id as given by `GET /wallets`.	false
`.sourceAmount`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account on swap completion.	false
`.targetAsset`	string	Indicates the asset credited to your account on swap completion. Matches an asset id as given by `GET /wallets`.	false
`.targetAmount`	string	A numeric string indicating the total amount of `targetAsset` credited to your account on swap completion.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this swap.	false
`.type`	string	The type of blockchain transaction. This is always set to `SWAP` (blockchain transaction executing the currency swap).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.blockchain`	string	The blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.blockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/swapprotected

Retrieves details of a given swap.

Request

curl 'https://www.coinqvest.com/api/v1/swap?id=xxx'

Request Params

Key	Type	Description	Default	Mandatory
`id`	string(12)	Unique identifier as given by `GET /deposits` or `POST /swap`.	null	mandatory

Success Response application/json

{
   "swap":{
      "id":"5074f4ee055d",
      "state":"COMPLETED",
      "type":"SOURCE_SPECIFIED",
      "origin":"API",
      "createTime":"2021-05-06T22:15:37+00:00",
      "completeTime":"2021-05-06T22:16:01+00:00",
      "expireTime":"2021-05-06T23:15:37+00:00",
      "sourceAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "sourceAmount":"100.0000000",
      "targetAssetIssuer":"XLM:NATIVE",
      "targetAmount":"243.3928192",
      "blockchainTransactions":[
        {
           "type":"SWAP",
           "typeDescription":"Blockchain transaction executed during the swap on the Stellar Network.",
           "blockchain":"Stellar Network",
           "blockchainAssetCode":"XLM",
           "tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7efaab614a7",
           "amount":"243.3928192",
           "amountAssetCode":"XLM"
        }
      ]
   }
}

Success Response Attributes

Name	Type	Description	Nullable
`.swap{}`	object	An object containing swap information.	false
`.id`	string(12)	Unique identifier of this swap.	false
`.state`	string	The swap state. The list of possible values is `COMPLETED` , `PENDING_API_COMMIT`, `PROCESSING`, and `FAILED`.	false
`.type`	string	The swap type. `SOURCE_SPECIFIED` indicates that you specified the source amount. `TARGET_SPECIFIED` indicates that you specified the target amount.	false
`.origin`	string	Indicates how the swap was initiated, either `UI` or `API`.	false
`.createTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was created.	false
`.completeTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was completed. This value is set when the swap state is `COMPLETED` and otherwise it is null.	true
`.expireTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. Please send the API commit before the expiration time to ensure swap execution.	true
`.sourceAsset`	string	Indicates the asset debited from your account on swap completion. Matches an asset id as given by `GET /wallets`.	false
`.sourceAmount`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account on swap completion.	false
`.targetAsset`	string	Indicates the asset credited to your account on swap completion. Matches an asset id as given by `GET /wallets`.	false
`.targetAmount`	string	A numeric string indicating the total amount of `targetAsset` credited to your account on swap completion.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this swap.	false
`.type`	string	The type of blockchain transaction. This is always set to `SWAP` (blockchain transaction executing the currency swap).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.blockchain`	string	The blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.blockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/swapsprotected

Retrieves a list of your swaps (in descending order from newest to oldest).

Request

curl 'https://www.coinqvest.com/api/v1/swaps?limit=250&offset=0'

Request Params

Key	Type	Description	Default	Mandatory
`limit`	integer	Maximum number of swap objects to be retrieved.	250	optional
`offset`	integer	Specifies the pagination offset.	0	optional

Success Response application/json

{
   "count":2,
   "limit":10,
   "offset":0,
   "deposits":[
      {
         "swap":{
            "id":"23b4f4ee055d",
            "state":"PENDING_API_COMMIT",
            "type":"SOURCE_SPECIFIED",
            "origin":"API",
            "createTime":"2021-05-06T22:15:37+00:00",
            "completeTime":null,
            "expireTime":"2021-05-06T23:15:37+00:00",
            "sourceAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "sourceAmount":"10.0000000",
            "targetAssetIssuer":"XLM:NATIVE",
            "targetAmount":"24.1392819",
            "blockchainTransactions":[]
         }
      },
      {
         "swap":{
            "id":"5074f4ee055d",
            "state":"COMPLETED",
            "type":"SOURCE_SPECIFIED",
            "origin":"API",
            "createTime":"2021-05-06T22:15:37+00:00",
            "completeTime":"2021-05-06T22:16:01+00:00",
            "expireTime":"2021-05-06T23:15:37+00:00",
            "sourceAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "sourceAmount":"100.0000000",
            "targetAssetIssuer":"XLM:NATIVE",
            "targetAmount":"243.3928192",
            "blockchainTransactions":[
               {
                  "type":"SWAP",
                  "typeDescription":"Blockchain transaction executed during the swap on the Stellar Network.",
                  "blockchain":"Stellar Network",
                  "blockchainAssetCode":"XLM",
                  "tx":"ac8f8554b273c8a0191309154bd108346c333b7f9dc3ada8f080c7efaab614a7",
                  "amount":"243.3928192",
                  "amountAssetCode":"XLM"
               }
            ]
         }
      }
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`.count`	integer	The total number of swaps initiated in this account.	false
`.limit`	integer	The limit argument used in this request.	false
`.offset`	integer	The pagination offset used in this request.	false
`.swaps[]`	array	A list of swap objects.	false
`.id`	string(12)	Unique identifier of this swap.	false
`.state`	string	The swap state. The list of possible values is `COMPLETED` , `PENDING_API_COMMIT`, `PROCESSING`, and `FAILED`.	false
`.type`	string	The swap type. `SOURCE_SPECIFIED` indicates that you specified the source amount. `TARGET_SPECIFIED` indicates that you specified the target amount.	false
`.origin`	string	Indicates how the swap was initiated, either `UI` or `API`.	false
`.createTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was created.	false
`.completeTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the swap was completed. This value is set when the swap state is `COMPLETED` and otherwise it is null.	true
`.expireTime`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the guaranteed conversion rate expires. Please send the API commit before the expiration time to ensure swap execution.	true
`.sourceAsset`	string	Indicates the asset debited from your account on swap completion. Matches an asset id as given by `GET /wallets`.	false
`.sourceAmount`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account on swap completion.	false
`.targetAsset`	string	Indicates the asset credited to your account on swap completion. Matches an asset id as given by `GET /wallets`.	false
`.targetAmount`	string	A numeric string indicating the total amount of `targetAsset` credited to your account on swap completion.	false
`.blockchainTransactions[]`	array	A list of blockchain transactions associated with this swap.	false
`.type`	string	The type of blockchain transaction. This is always set to `SWAP` (blockchain transaction executing the currency swap).	false
`.typeDescription`	string	An explanation of the above blockchain transaction `type` in English plain text.	false
`.blockchain`	string	The blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.blockchainAssetCode`	string	The native asset code of the blockchain (`GET /blockchains`) on which this transaction was executed.	false
`.tx`	string	The corresponding blockchain transaction id.	false
`.amount`	string	The amount transferred during in this transaction.	false
`.amountAssetCode`	string	The asset code of the amount transferred in this transaction.	false

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/withdrawalprotected

This endpoint is invoked when you wish to withdraw funds from the COINQVEST platform into your own cryptocurrency wallets or fiat bank accounts.

Withdrawals are a two-step process. In the first step, you submit the source and target assets as well as the source amount. Upon successful completion, this endpoint returns a withdrawal object, which includes the guaranteed amount that will be deposited into the target account. In the second step, you analyze the exchange rate and confirm the withdrawal by submitting a subsequent request to the POST /withdrawal/commit endpoint.

Example Request

curl -X POST https://www.coinqvest.com/api/v1/withdrawal \
     -d "@payload.json"

Where payload.json is a JSON object.

Example Payload (Withdrawal to the Stellar Network)

{
   "sourceAsset":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
   "sourceAmount":10,
   "targetNetwork":"XLM",
   "targetAsset":"XLM:NATIVE",
   "targetAccount":{
      "account":"GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ",
      "memo":"EXODUS",
      "memoType":"text"
   }
}

In above example 10 USD are withdrawn from your COINQVEST wallet, converted into XLM and sent to the Stellar Network account GASKY...6EDCQ.

Example Payload (Withdrawal to an EU IBAN Bank Account)

{
   "sourceAsset":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
   "sourceAmount":100,
   "targetNetwork":"EUR",
   "targetAccount":{
      "iban":"DE23100110012624331587",
      "swift":"NTSBDEB1XXX"
   }
}

In above example 100 USD are withdrawn from your COINQVEST wallet, converted into EUR and sent to the EU bank account with the IBAN DE23...1587 at SWIFT NTS...XXX.

Example Payload (Withdrawal to the Bitcoin Network)

{
   "sourceAsset":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
   "sourceAmount":100,
   "targetNetwork":"BTC",
   "targetAccount":{
      "address":"bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew23"
   },
   "relay":"BTC:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5"
}

In above example 100 USD are withdrawn from your COINQVEST wallet, converted into native BTC and sent to the Bitcoin address bc1q...ew23. The payload specifically elects the asset issuer BTC:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5 (Stellarport) to process this payment and convert the funds on COINQVEST into native Bitcoin. See GET /asset-issuers for a list of available asset issuers.

Example Payload (Withdrawal to an NGN Bank Account)

{
   "sourceAsset":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
   "sourceAmount":100,
   "targetNetwork":"NGN",
   "targetAccount":{
      "nuban":"4791494548",
      "bankName":"FirstBank"
   }
}

In above example 100 USD are withdrawn from your COINQVEST wallet, converted into Nigerian Naira (NGN) and sent to the NUBAN bank account 4791494548 at FirstBank.

Example Payload (Withdrawal to an BRL Bank Account via PIX)

{
   "sourceAsset":"BRL:GDVKY2GU2DRXWTBEYJJWSFXIGBZV6AZNBVVSUHEPZI54LIS6BA7DVVSP",
   "sourceAmount":10000,
   "targetNetwork":"BRL",
   "targetAccount":{
      "pixKey":"email@example.org",
      "taxId":"528.963.222-01"
   }
}

In above example 10,000 BRL are withdrawn from your COINQVEST wallet, converted into Brazilian Real (BRL) and sent to the bank account associated with the PIX key email@example.org.

Request Params (POST)

Key Type Description Nullable Mandatory

.sourceAsset string Specifies the source asset from which you want to withdraw. Invoke GET /wallets to inspect which assets you currently hold. false mandatory

.sourceAmount string The exact amount you wish to withdraw. Invoke GET /wallets to inspect how much sourceAsset you currently hold. false mandatory

.targetNetwork string(3) Specifies the blockchain or fiat currency to which you want to withdraw. This field takes a blockchain asset code as given by GET /blockchains or a fiat currency asset code as given by GET /fiat-currencies. Examples: Set this to XLM if you wish to withdraw to the Stellar Network, to EUR if you wish to withdraw to an EU IBAN bank account or BTC if you wish to withdraw to the Bitcoin network. false mandatory

.targetAsset string This field is only relevant when the targetNetwork is set to XLM (withdrawal to the Stellar Network).

It specifies the target asset you want the recipient to be credited in. If no value is given then the target account is credited in sourceAsset.

Required format is XLM:NATIVE for XLM or (e.g.) USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN for USDC by Circle. true optional

.targetAccount

object

An object describing the target account to which the payment should be sent.

This field is mutable and its contents depend on the requirements of the related targetNetwork used in the request.

Field Attributes for withdrawals to ARS

`cbu`	The recipient's bank account number (CBU or CVU). This CBU must match the account information verified on COINQVEST.
`cuitPersonal`	Your personal tax id associated with the target CBU and your COINQVEST account.
`cuitCompany`	Business accounts need to provide an additional CUIT, issued towards the company that owns the bank account and is verified on COINQVEST.

Field Attributes for withdrawals to BRL

`pixKey`	The PIX key associated with the recipient bank account. Typically a phone number, CPF, email address, or random key.
`taxId`	The recipient's tax id. CNPJ format (`00.000.000/0000-00`) for corporate identities or CPF format (`000.000.000-00`) for individuals.

Field Attributes for withdrawals to EUR

`iban`	The recipient bank account's IBAN.
`swift`	The recipient bank account's SWIFT/BIC.

Field Attributes for withdrawals to NGN

`nuban`	The recipient bank account's NUBAN.
`bankName`	The recipient bank's name. Can be one of the below. `AccessBank`, `CitiBank`, `DiamondBank`, `Ecobank`, `EnterpriseBank`, `FCMB`, `FidelityBank`, `FirstBank`, `GTBank`, `Heritage`, `JaizBank`, `KeystoneBank`, `ProvidusBank`, `SkyeBank`, `Stanbic`, `StandardChartered`, `SterlingBank`, `SuntrustBank`, `UBA`, `UnionBank`, `UnityBank`, `WemaBank`, `ZenithBank`.

Field Attributes for withdrawals to BTC, ETH, LTC

address The address to which the withdrawal should be sent.

Field Attributes for withdrawals to XLM (any Stellar Network asset)

`account`	The account to which the withdrawal should be sent.
`memo`	The Stellar memo used in this payment. Can be `null`.
`memoType`	The type of memo, if any. Can be `null`.

false

mandatory

.relay string This field takes a assetIssuerId as given by GET /asset-issuers and is only relevant for withdrawals to fiat currencies and blockchains other than the Stellar Network. It specifies the asset issuer (Stellar Anchor) that should be used to process the payment and convert funds into native USD, NGN, EUR, BTC, ETH, LTC. If no relay is specified then the option with the highest resulting target amount (your most economic option) is automatically selected. See GET /asset-issuers for a list of available options. true optional

Success Response application/json

{
   "withdrawal":{
      "id":"12d72c3c8145",
      "type":"WITHDRAWAL",
      "state":"PENDING_API_COMMIT",
      "origin":"API",
      "timestamp":"2020-03-04T19:54:47+02:00",
      "sourceAssetCode":"USD",
      "sourceAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
      "sourceAmount":"142.3156600",
      "targetAssetCode":"NGNT",
      "targetAssetIssuer":"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
      "targetAmount":"30727.1358200",
      "fee":"200.0000000",
      "targetBlockchain":null,
      "targetFiatCurrency":"NGN",
      "transactionId":null,
      "targetAccount":{
         "nuban":"4791494548",
         "bankName":"FirstBank"
      }
   }
}

Above response is issued in response to a withdrawal request over 142.315660 USD, conversion into NGN and deposit into an NGN bank account in the form of native NGN fiat money (targetFiatCurrency is set to NGN).

Next Step

Your application analyzes the API response and determines whether it wants to accept the guaranteed targetAmount. To finalize the withdrawal, you confirm it by invoking the POST /withdrawal/commit endpoint.

Success Response Attributes

Name Type Description Nullable

.withdrawal{} object An object with details about the withdrawal. false

.id string(12) Unique identifier of this withdrawal. false

.type string The withdrawal type. Currently, the only existing value is WITHDRAWAL. false

.state string This field represents the withdrawal state. The only possible state in a response to the POST /withdrawal endpoint is PENDING_API_COMMIT. This state indicates that the withdrawal has been initialized, a target amount was calculated and the withdrawal is awaiting confirmation by the POST /withdrawal/commit endpoint. false

.origin string This field indicates how the withdrawal was initiated, either UI or API. The only possible origin in a response to the POST /withdrawal endpoint is API. false

.timestamp timestamp W3C formatted time stamp with time zone (UTC) specifying when the withdrawal was initiated. false

.sourceAssetCode string The asset code debited from your account (e.g USD). false

.sourceAssetIssuer string Identifier of the issuer of the asset debited from your account, see GET /asset-issuers. Invoke GET /wallets to inspect which assets you currently hold. false

.sourceAmount string The amount debited from your account. false

.targetAssetCode string This field represents the asset sent to the target account (e.g. USD, XLM, ETH). This can be a blockchain or fiat currency identifier. false

.targetAssetIssuer string This field indicates the entity that will process this withdrawal on your behalf, see GET /asset-issuers. false

.targetAmount string This field displays the guaranteed amount received in the target account. false

.fee string This field displays the withdrawal fee kept by the processing entity (the asset issuer used in this transaction, GET /asset-issuers).

Your account is debited the equivalent of the sum of
fee + targetAmount. false

.targetBlockchain string(3) References the blockchain to which this withdrawal will be sent (see GET /blockchains). This field is null if the withdrawal was sent to a fiat currency bank account. true

.targetFiatCurrency string(3) References the fiat currency to which this withdrawal will be sent (see GET /fiat-currencies). This field is null if the withdrawal was sent to a blockchain account. true

.transactionId string(64) References the related transaction on the Stellar Network. The only value in a response to the POST /withdrawal endpoint is null because the transaction does not execute until the withdrawal is confirmed by invoking the POST /withdrawal/commit endpoint. true

.targetAccount

object

An object describing the target account to which the payment will be sent.

This field is mutable and its contents depend on the requirements of the related targetNetwork originally used in the request.

Field Attributes for withdrawals to ARS

cbu The recipient's bank account number (CBU).

Field Attributes for withdrawals to BRL

`accountNumber`	The recipient's bank account number.
`branchNumber`	The recipient bank's branch number.
`bankNumber`	The recipient bank's financial institution number (3 digits).

Field attributes for withdrawals to EUR

`iban`	The recipient bank account's IBAN.
`swift`	The recipient bank account's SWIFT/BIC.

Field attributes for withdrawals to NGN

`nuban`	The recipient bank account's NUBAN.
`bankName`	The recipient bank's name.

Field attributes for withdrawals to USD

`accountNumber`	The recipient's bank account number.
`routingNumber`	The recipient's bank routing number.

Field attributes for withdrawals to BTC, ETH, LTC

address The address to which the withdrawal should be sent.

Field attributes for withdrawals to XLM (any Stellar Network asset)

`account`	The account to which the withdrawal should be sent.
`memo`	The Stellar memo used in this payment. Can be `null`.
`memoType`	The type of memo, if any. Can be `null`.

false

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

POST/withdrawal/commitprotected

This endpoint is a continuation of the withdrawal process started in POST /withdrawal. If you aren't familiar with how to initialize a withdrawal process yet, please start here.

Important: Please note that this endpoint requires a long timeout setting (we recommend 120 seconds) as it waits for blockchain confirmation before returning a response.

This endpoint takes a withdrawalId parameter as given by POST /withdrawal. Upon successful completion, the withdrawal is committed and processed by COINQVEST. Its state changes from PENDING_API_COMMIT to COMPLETED in the response and a blockchain transaction id is returned.

In the previous step POST /withdrawal gave you an object like this:

Example Response (as given by `POST /withdrawal`)

{
   "withdrawal":{
      "id":"12d72c3c8145",
      "type":"WITHDRAWAL",
      "state":"PENDING_API_COMMIT",
      "origin":"API",
      "timestamp":"2020-03-04T19:54:47+02:00",
      "sourceAssetCode":"USD",
      "sourceAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
      "sourceAmount":"142.3156600",
      "targetAssetCode":"NGNT",
      "targetAssetIssuer":"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
      "targetAmount":"30727.1358200",
      "withdrawalFee":"200.0000000",
      "targetBlockchain":null,
      "targetFiatCurrency":"NGN",
      "transactionId":null,
      "targetAccount":{
         "nuban":"4791494548",
         "bankName":"FirstBank"
      }
   }
}

As a prerequisite to invoke this endpoint, you should have received a response as above from POST /withdrawal. Its state is PENDING_API_COMMIT, which means that the withdrawal is awaiting final confirmation through this endpoint. Upon inspection and acceptance of the given targetAmount, you need to invoke POST /withdrawal/commit (this endpoint) to confirm the withdrawal and submit it for processing.

Request

curl -X POST 'https://www.coinqvest.com/api/v1/withdrawal/commit'
    -d "@payload.json"

Where payload.json is a JSON object.

Example Payload

{
  "withdrawalId":"12d72c3c8145"
}

Request Params

Key	Type	Description	Default	Mandatory
`withdrawalId`	string(12)	Unique identifier as given by `POST /withdrawal`.	null	mandatory

Success Response application/json

{
   "withdrawal":{
      "id":"12d72c3c8145",
      "type":"WITHDRAWAL",
      "state":"COMPLETED",
      "origin":"UI",
      "timestamp":"2020-03-04T19:54:47+02:00",
      "sourceAssetCode":"USD",
      "sourceAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
      "sourceAmount":"142.3156600",
      "targetAssetCode":"NGNT",
      "targetAssetIssuer":"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
      "targetAmount":"30727.1358200",
      "withdrawalFee":"200.0000000",
      "targetBlockchain":null,
      "targetFiatCurrency":"NGN",
      "transactionId":"62070ddf01d98e4cb3dc25e5052810259013df28a9e551d948fa2e1b1757de09",
      "targetAccount":{
         "nuban":"4791494548",
         "bankName":"FirstBank"
      }
   }
}

Success Response Attributes

Name Type Description Nullable

.withdrawal{} object An object with details about the withdrawal. false

.id string(12) Unique identifier of this withdrawal. false

.type string The withdrawal type. Currently, the only existing value is WITHDRAWAL. false

.state string This field represents the withdrawal state. The only possible state in a response to the POST /withdrawal/commit endpoint is COMPLETED . This state indicates that the withdrawal has been processed and the money is on the way (or has been deposited if you're withdrawing to a fast blockchain) . false

.origin string This field indicates how the withdrawal was initiated, either UI or API. The only possible origin in a response to the POST /withdrawal/commit endpoint is API. false

.timestamp timestamp W3C formatted time stamp with time zone (UTC) specifying when the withdrawal was initiated. false

.sourceAssetCode string The asset code debited from your account (e.g USD). false

.sourceAssetIssuer string Identifier of the issuer of the asset debited from your account, see GET /asset-issuers. false

.sourceAmount string The amount debited from your account. false

.targetAssetCode string This field represents the asset sent to the target account (e.g. USD, XLM, ETH). This can be a blockchain or fiat currency identifier. false

.targetAssetIssuer string This field indicates the entity that processed this withdrawal on your behalf, see GET /asset-issuers. false

.targetAmount string This field displays the amount received in the target account. false

.fee string This field displays the withdrawal fee kept by the processing entity (the asset issuer used in this transaction, GET /asset-issuers).

Your account was debited the equivalent of the sum of
fee + targetAmount. false

.targetBlockchain string(3) References the blockchain to which this withdrawal was sent (see GET /blockchains). This field is null if the withdrawal was sent to a fiat currency bank account. true

.targetFiatCurrency string(3) References the fiat currency to which this withdrawal was sent (see GET /fiat-currencies). This field is null if the withdrawal was sent to a blockchain account. true

.transactionId string(64) References the related transaction on the Stellar Network. true

.targetAccount

object

An object describing the target account to which the payment was sent.

This field is mutable and its contents depend on the requirements of the related targetBlockchain or targetFiatCurrency.

Field Attributes for withdrawals to ARS

cbu The recipient's bank account number (CBU).

Field Attributes for withdrawals to BRL

`accountNumber`	The recipient's bank account number.
`branchNumber`	The recipient bank's branch number.
`bankNumber`	The recipient bank's financial institution number (3 digits).

Field attributes for withdrawals to EUR

`iban`	The recipient bank account's IBAN.
`swift`	The recipient bank account's SWIFT/BIC.

Field attributes for withdrawals to NGN

`nuban`	The recipient bank account's NUBAN.
`bankName`	The recipient bank's name.

Field attributes for withdrawals to USD

`accountNumber`	The recipient's bank account number.
`routingNumber`	The recipient's bank routing number.

Field attributes for withdrawals to BTC, ETH, LTC

address The address to which the withdrawal was sent.

Field attributes for withdrawals to XLM (any Stellar Network asset)

`account`	The account to which the withdrawal was sent.
`memo`	The Stellar memo used in this payment. Can be `null`.
`memoType`	The type of memo, if any. Can be `null`.

false

Error Response application/json

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[ ]	A list of strings explaining the error.	false

GET/withdrawalprotected

Retrieves details of a given withdrawal.

Request

curl 'https://www.coinqvest.com/api/v1/withdrawal?id=xxx'

Request Params

Key	Type	Description	Default	Mandatory
`id`	string(12)	Unique identifier as given by `GET /withdrawals` or `POST /withdrawal`.	null	mandatory

Success Response application/json

{
   "withdrawal":{
      "id":"12d72c3c8145",
      "type":"WITHDRAWAL",
      "state":"COMPLETED",
      "origin":"UI",
      "timestamp":"2020-03-04T19:54:47+02:00",
      "sourceAssetCode":"USD",
      "sourceAssetIssuer":"USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
      "sourceAmount":"142.3156600",
      "targetAssetCode":"NGNT",
      "targetAssetIssuer":"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
      "targetAmount":"30727.1358200",
      "fee":"200.0000000",
      "targetBlockchain":null,
      "targetFiatCurrency":"NGN",
      "transactionId":"62070ddf01d98e4cb3dc25e5052810259013df28a9e551d948fa2e1b1757de09",
      "targetAccount":{
         "nuban":"4791494548",
         "bankName":"FirstBank"
      }
   }
}

Success Response Attributes

Name Type Description Nullable

.withdrawal{} object An object with details about the withdrawal. false

.id string(12) Unique identifier of this withdrawal. false

.type string The debit type. Currently, the only existing value is WITHDRAWAL. false

.state string Represents the withdrawal state. The list of possible values is COMPLETED , PROCESSING, PENDING_API_COMMIT and FAILED. false

.origin string Indicates how the withdrawal was initiated, either UI or API. false