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 or blockchain deposit address on Bitcoin, Lightning, Litecoin, or Stellar to get paid.

Checkouts

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 (that can be fully branded) 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. Click here to learn more about building checkouts.

Wallets and Deposits

Your COINQVEST account comes equipped with dedicated deposit addresses for Bitcoin, Lightning, Litecoin, and select assets on the Stellar Network. You can receive blockchain payments within seconds after registering. The GET /wallets and POST /deposit-address endpoints return your blockchain addresses to start receiving custom deposits.

Swaps and Transfers

Once funds arrive in your account, either via completed checkouts or custom deposits, you have instant access to them and the ability to swap them into other assets or transfer them to other blockchain accounts (we recommend to always forward funds into self-custody on cold storage) and bank accounts. The POST /swap and POST /withdrawal endpoints will get you started on your first swaps and transfers.

Financial Reports and Accounting

We don't leave you hanging with an obscure and complicated blockchain payment trail to figure out by yourself. All transactions on COINQVEST are aggregated into the Financial Reports section of your account and can even be associated with counter-parties, such as customers and beneficiaries. We provide CSV reports, charts, and beautiful analytics for all your in-house accounting needs.

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's Payments API

API Tools and Event Logging
An Introduction to COINQVEST's Payments 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.

Magento
Official COINQVEST Extension for Magento 2

PrestaShop
Official COINQVEST Extension for PrestaShop

Shopify
Official COINQVEST Integration for Shopify

WooCommerce
Official COINQVEST Plugin for WooCommerce

Wordpress
Official COINQVEST Plugin for Wordpress

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

Building Checkouts

The first step to get started is to decide whether you want to use our hosted checkout experience (which can be fully branded) or implement self-hosted checkouts where you control the entire payment process on your own servers via our backend APIs.

Creating Self-Hosted Checkouts (Backend API)

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.

Creating Hosted Checkouts (Payment Links)

Hosted checkouts (which can be fully branded) are the simplest form of getting paid using the COINQVEST platform. The POST /checkout/hosted API endpoint creates and returns a payment link to a convenient checkout page on COINQVEST servers (you can use your own domain via Brand Connect if you want). 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":{
      "billingCurrency":"USD",
      "lineItems":[
         {
            "description":"PCI Graphics Card",
            "netAmount":169.99
         }
      ]
   },
   "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

Above example creates a charge for an item at 169.99 EUR. You can configure more details, such as shipping costs, discounts, taxes, the related customer, as well as your preferred settlement asset 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":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "settlementAmountRequired":"10.0000000",
         "settlementAmountReceived":"10.0000000",
         "settlementAmountFeePaid": "0",
         "sourceAssetId":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
         "sourceAmountRequired":"0.0069518",
         "sourceAmountReceived":"0.0069518",
         "sourceNetwork": "ETHEREUM",
         "sourceNetworkName": "Ethereum",
         "depositAddress": "0xA2Bf179E09C503262E418FC72261837726f68F36",
         "blockchainTransactions":[
            {
               "type":"ORIGIN",
               "typeDescription":"Blockchain payment transaction initiated by customer.",
               "network": "ETHEREUM",
               "networkName": "Ethereum",
               "timestamp": "2020-09-16T21:34:32+00:00",
               "tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
               "amount":"0.0069518",
               "amountAssetCode":"ETH",
               "exception":null
            },
            {
               "type":"TRANSFER",
               "typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
               "network": "STELLAR",
               "networkName": "Stellar",
               "timestamp": "2020-09-16T21:34:37+00:00",
               "tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
               "amount":"0.0069518",
               "amountAssetCode":"ETH",
               "exception":null
            },
            {
               "type":"SETTLEMENT",
               "typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
               "network": "STELLAR",
               "networkName": "Stellar",
               "timestamp": "2020-09-16T21:34:42+00:00",
               "tx":"63dab32ba979e41e43a718aaf51c61cadf6dec944715d9fd04f1f61d9ee8800f",
               "amount":"10.0000000",
               "amountAssetCode":"USD",
               "exception":null
            }
         ],
         "payload":{
            "charge":{
               "lineItems":[
                  {
                     "description":"PCI Graphics Card",
                     "quantity":"1",
                     "netAmount":"169.99",
                     "productId":"P1234"
                  }
               ],
               "billingCurrency":"USD",
               "customerId":"a2df67b61725"
            },
            "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
         }
      }
   }
}

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.

Brand Connect

Brand Connect customizes COINQVEST's hosted checkouts to your own brand, web domain, custom logo, images, and fully skinned UI. It can run on coinqvest.com or on your own web domain with a simple docker container deployment.

Brand Connect specifically caters to payment service providers who want to take advantage of COINQVEST's all-in-one checkout flow under their own corporate identity, including all its perks, such as exception handling for overpaid, underpaid, multiple transactions, refunds, or customer management. Of course we won't stop you if you are not a payment service provider and simply want to make your online shop's checkout page match your website's overall look and feel.

Brand Configuration

You can configure the appearance of your checkouts via our Brand Connect web interface in your account settings. Follow these steps to get your custom branding up and running.

1. Enable Brand Connect in your account settings
2. Continue in account settings to configure Brand Information, Images, Fonts, and Colors

Your checkout pages are now customized with your company's company logo, favicon, custom crypto images, font types, and your very own color scheme. When you inspect your checkout pages you will notice that your custom UI skin is already applied and there is no mention of COINQVEST being your service provider.

Domain Name Configuration

By default your custom branding runs on the coinqvest.com web domain, but you can choose to make your checkouts accessible through your very own web domain instead. This is particularly useful if you provide payment services to your clients and want to use COINQVEST but host the checkout flow in your own web application or APIs and maintain the full appearance of your own corporate identity.

Web domain integration is implemented by deploying the Brand Connect docker container (GitHub) into your own hosting environment and pointing your desired custom web domain at it via DNS config. The docker container acts as a proxy for HTTP traffic between the public and the COINQVEST servers and enables your custom branded UI. Follow these steps to host checkouts under your own domain.

1. Enable Brand Connect in your account settings
2. Continue in account settings to configure Brand Information, Images, Fonts, and Colors
3. Specify the web domain for your checkouts and obtain your CQ_BRANDING_KEY (by completing the steps above)
4. Deploy the Brand Connect docker container by with your own SSL certificate
5. Point your web domain's DNS configuration at the IP address you're running the docker container on.

That's it. Your COINQVEST checkout pages now live on your very own web domain and are fully integrated with your corporate identity's look and feel. Read more on GitHub.

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 Payments API 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

GET/networksprotected

Returns a list of blockchain and bank networks supported by the COINQVEST platform.

Request

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

Success Response application/json

{
   "networks":[
      {
         "id":"BITCOIN",
         "name":"Bitcoin",
         "type":"BLOCKCHAIN",
         "imageSrc":"/images/icon-btc-88.png",
         "deposits":true,
         "withdrawals":true,
         "bridged": true,
         "assets":[
            "BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF"
         ]
      },
      {
         "id":"SWIFT",
         "name":"SWIFT",
         "type":"BANK",
         "imageSrc":"/images/icon-swift-88.png",
         "deposits":false,
         "withdrawals":true,
         "bridged": true,
         "assets":[
            "EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
            "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V"
         ]
      },
      {
         "id":"STELLAR",
         "name":"Stellar",
         "type":"BLOCKCHAIN",
         "imageSrc":"/images/icon-xlm-88.png",
         "deposits":true,
         "withdrawals":true,
         "bridged": false,
         "assets":[
            "XLM:NATIVE",
            "EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
            "BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
            "ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
            "LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP",
            "NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
            "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
            "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "ARS:GCYE7C77EB5AWAA25R5XMWNI2EDOKTTFTTPZKM2SR5DI4B4WFD52DARS",
            "BRL:GDVKY2GU2DRXWTBEYJJWSFXIGBZV6AZNBVVSUHEPZI54LIS6BA7DVVSP"
         ]
      },
      {
         "id":"ETHEREUM",
         "name":"Ethereum",
         "type":"BLOCKCHAIN",
         "imageSrc":"/images/icon-eth-88.png",
         "deposits":true,
         "withdrawals":true,
         "bridged": true,
         "assets":[
            "ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
            "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V"
         ]
      },
      {
         "id":"LITECOIN",
         "name":"Litecoin",
         "type":"BLOCKCHAIN",
         "imageSrc":"/images/icon-ltc-88.png",
         "deposits":true,
         "withdrawals":true,
         "bridged": true,
         "assets":[
            "LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP"
         ]
      },
      {
         "id":"SEPA",
         "name":"SEPA",
         "type":"BANK",
         "imageSrc":"/images/icon-sepa-88.png",
         "deposits":false,
         "withdrawals":true,
         "bridged": true,
         "assets":[
            "EURT:GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S",
            "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
            "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
         ]
      },
      {
         "id":"CBU",
         "name":"Argentine CBU/CVU",
         "type":"BANK",
         "imageSrc":"/images/icon-ars-88.png",
         "deposits":false,
         "withdrawals":true,
         "bridged": true,
         "assets":[
            "ARS:GCYE7C77EB5AWAA25R5XMWNI2EDOKTTFTTPZKM2SR5DI4B4WFD52DARS"
         ]
      },
      {
         "id":"PIX",
         "name":"Brazilian PIX",
         "type":"BANK",
         "imageSrc":"/images/icon-brl-88.png",
         "deposits":false,
         "withdrawals":true,
         "bridged": true,
         "assets":[
            "BRL:GDVKY2GU2DRXWTBEYJJWSFXIGBZV6AZNBVVSUHEPZI54LIS6BA7DVVSP"
         ]
      }
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`.networks[]`	array	A list objects representing a blockchain or bank network.	false
`.id`	string	The network identifier.	false
`.name`	string	The network name.	false
`.type`	string	The network type. Can be either `BLOCKCHAIN` or `BANK`.	false
`.imageSrc`	string	The URL of the COINQVEST icon depicting the network. A path relative to www.coinqvest.com.	false
`.deposits`	boolean	Indicates whether this network can be used as to originate payments towards checkouts and deposits.	false
`.withdrawals`	boolean	Indicates whether this network can be receive to transfers and withdrawals.	false
`.bridged`	boolean	Indicates whether this network is native to the COINQVEST platform or bridged via Stellar (SEP-6 or OTC).	false
`.assets`	array	A list of asset identifiers as given by `GET /assets` indicating the assets available for redemption and reception via the network.	false

Error Response application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Error Response Params

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

GET/assetsprotected

Returns a list of Stellar assets supported by the COINQVEST platform. Assets can be redeemed to and received from the Stellar Network and other payment networks (if they are bridge assets).

For example, BTC assets are bridge assets and can be redeemed to and received from Stellar and the Bitcoin network directly. USDC assets are also bridge assets and can be redeemed to SWIFT and SEPA as well as the Stellar Network.

Inspect the network relations to identify supported networks for an asset.

Request

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

Success Response application/json

{
   "assets":[
      {
         "id":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
         "assetCode":"BTC",
         "assetIssuer":"GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
         "name":"Bitcoin",
         "group":"BTC",
         "groupImageSrc":"/images/icon-btc-88.png",
         "issuerName":"Papaya",
         "issuerDomain":"apay.io",
         "issuerAddress":"Rapid SD Pty Ltd., Sydney, Australia",
         "imageSrc":"/images/icon-btc-88.png",
         "checkouts":true,
         "deposits":true,
         "settlement":true,
         "swaps":true,
         "transfers":true,
         "hexColor":"#f7931a",
         "riskLevel":"MEDIUM",
         "bridge":true,
         "networks":[
            "STELLAR",
            "BITCOIN"
         ]
      },
      {
         "id":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "assetCode":"USDC",
         "assetIssuer":"GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "name":"USD Coin",
         "group":"USD",
         "groupImageSrc":"/images/icon-usd-88.png",
         "issuerName":"Centre",
         "issuerDomain":"centre.io",
         "issuerAddress":"Centre Consortium LLC, United States",
         "imageSrc":"/images/icon-usdc-88.png",
         "checkouts":true,
         "deposits":true,
         "settlement":true,
         "swaps":true,
         "transfers":true,
         "hexColor":"#2775ca",
         "riskLevel":"LOW",
         "bridge":true,
         "networks":[
            "STELLAR",
            "SWIFT",
            "SEPA"
         ]
      },
      {
         "id":"XLM:NATIVE",
         "assetCode":"XLM",
         "assetIssuer":"NATIVE",
         "name":"Stellar Lumens",
         "group":"XLM",
         "groupImageSrc":"/images/icon-xlm-88.png",
         "issuerName":"SDF",
         "issuerDomain":"stellar.org",
         "issuerAddress":"Stellar Development Foundation, San Francisco, CA, United States",
         "imageSrc":"/images/icon-xlm-88.png",
         "checkouts":true,
         "deposits":true,
         "settlement":true,
         "swaps":true,
         "transfers":true,
         "hexColor":"#5894ca",
         "riskLevel":"LOW",
         "bridge":false,
         "networks":[
            "STELLAR"
         ]
      }
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`.assets[]`	array	A list objects representing a Stellar asset.	false
`.id`	string	The identifier of the asset.	false
`.assetCode`	string	The asset code.	false
`.assetIssuer`	string	The identifier of the asset issuer on the Stellar Network.	false
`.name`	string	The asset name.	false
`.group`	string	The group to which the asset belongs. For example, USDC and USDT belong to the USD group. BTC and BTCLN (Lightning) belong to the BTC group.	false
`.groupImageSrc`	string	The URL of the COINQVEST icon depicting the asset group. A path relative to www.coinqvest.com.	false
`.issuerName`	string	The asset issuer name in English plain text.	false
`.issuerDomain`	string	The asset issuer's web domain.	false
`.issuerAddress`	string	The asset issuer's physical address.	false
`.imageSrc`	string	The URL of the COINQVEST icon depicting the asset. A path relative to www.coinqvest.com.	false
`.checkouts`	boolean	Indicates whether this asset can be used as payment method in checkouts.	false
`.deposits`	boolean	Indicates whether this asset can be used as payment method in deposits.	false
`.swaps`	boolean	Indicates whether this asset can be used as source or target asset in swaps.	false
`.transfers`	boolean	Indicates whether this asset can be used as target assets in transfers and withdrawals.	false
`.hexColor`	string(7)	COINQVEST's color code for this asset. Useful for charts and other visualizations.	false
`.riskLevel`	string	Indicating the assets risk level as `LOW`, `MEDIUM`, or `HIGH`. Your risk tolerance can be configured in the (browser-based) settlement settings in your account. Assets with a `LOW` risk level are native to the Stellar Network and can be widely redeemed (e.g. XLM and USDC). Assets with a `MEDIUM` risk level assets are bridged onto the Stellar network by trusted custodians (anchors) and can be redeemed via SEP-6 or OTC via COINQVEST (e.g. BTC, LTC, ETH, Bitcoin Lightning BTC). Assets with a `HIGH` risk level are only available to you if manually enabled in your account settings (e.g. USDT).	false
`.bridge`	boolean	Indicates whether this asset is bridged via Stellar (SEP-6 or OTC).	false
`.networks`	array	A list of network identifiers as given by `GET /networks` indicating the networks on which payment transactions for this asset can be processed.	false

Error Response application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Error Response Params

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

GET/currenciesprotected

Returns a list of currencies supported by the COINQVEST platform.

Request

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

Success Response application/json

{
    "currencies": [
        {
            "assetCode": "BTC",
            "name": "Bitcoin",
            "type": "CRYPTO",
            "billing": true,
            "settlement": true,
            "payment": true
        },
        {
            "assetCode": "USD",
            "name": "US Dollar",
            "type": "FIAT",
            "billing": true,
            "settlement": true,
            "payment": false
        },
        {
            "assetCode": "XLM",
            "name": "Stellar Lumens",
            "type": "CRYPTO",
            "billing": true,
            "settlement": true,
            "payment": true
        }
}

Success Response Attributes

Name	Type	Description	Nullable
`.currencies[]`	array	A list objects representing a currency.	false
`.assetCode`	string	The asset code of the currency.	false
`.name`	string	The name of the currency.	false
`.type`	string	The currency type. Either `CRYPTO` or `FIAT`.	false
`.billing`	boolean	Indicates whether this currency can be specified as billing currency in checkout objects.	false
`.settlement`	boolean	Indicates whether this currency can be specified as settlement currency in checkout objects and deposits.	false
`.payment`	boolean	Indicates whether this currency can used as payment currency in checkout objects and deposits.	false

Error Response application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Error Response Params

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

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":{
      "billingCurrency":"EUR",
      "lineItems":[
         {
            "description":"PCI Graphics Card",
            "netAmount":169.99
         }
      ]
   },
   "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

Explanation of Above Payload Configuration

Above is the minimal configuration required to initiate a checkout. The charge is denominated in EUR and has exactly one line item at a cost of 169.99 EUR. The payment amount charged to by your customer in his crypto of choice is calculated against the total billing amount specified here.

Example Payload (Full)

{
   "charge":{
      "customerId":"716dad4c5e5f",
      "billingCurrency":"USD",
      "lineItems":[
         {
            "description":"PCI Graphics Card",
            "netAmount":199,
            "quantity":1,
            "productId":"P1234"
         }
      ],
      "discountItems":[
         {
            "description":"Loyalty Discount",
            "netAmount":5
         }
      ],
      "shippingCostItems":[
         {
            "description":"Shipping and Handling",
            "netAmount":3.99,
            "taxable":false
         }
      ],
      "taxItems":[
         {
            "name":"Sales Tax",
            "percent":0.0825
         }
      ]
   },
   "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
   "checkoutLanguage":"en",
   "webhook":"https://www.your-server.com/path/to/webhook",
   "pageSettings":{
      "returnUrl":"https://www.merchant.com/path/to/complete/checkout",
      "cancelUrl":"https://www.merchant.com/path/to/cancel/checkout",
      "shopName":"The T-Shirt Store Ltd.",
      "displayBuyerInfo":true,
      "displaySellerInfo":true
   },
   "meta":{
      "customAttribute":"customValue"
   },
   "anchors":{
      "BITCOIN":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
      "ETHEREUM":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR"
   }
}

Request Params (POST)

PRO Tip #1 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 #2 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
`.billingCurrency`	string	A currency code as given by `GET /currencies`. This is the customer facing billing currency quoted on the payment page in hosted checkouts and on invoices. Blockchain payment amounts are calculated against the billing currency and total amount specified in the charge. This is not the payment currency. Your customers will get to choose their preferred blockchain to make payment in their available asset regardless of the currency you specify here.	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`	numeric	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
`.settlementAsset`	string	An asset id as given by `GET /assets`. Specifies the asset you will be credited in when the checkout completes. Set to `ORIGIN` to get credited in the asset your customer pays in without any type of currency conversion.	ORIGIN	optional
`.checkoutLanguage`	string	A language code as given by `GET /languages`. 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`	en	optional
`.webhook`	string	A webhook URL on your server that listens for related checkout events as specified in webhook concepts.	null	optional
`.anchors{}`	object	An advanced setting to declare preferred Stellar SEP-0006 anchors to use during the checkout process. An object containing key value pairs, with the key being a network id as given by `GET /networks` and the value being an anchored asset id as given by `GET /assets`.	null	optional
`.pageSettings{}`	object	An object containing display settings for the customer facing hosted checkout page. Values provided here override your global account settings (if any).	null	optional
`.returnUrl`	string	Specifies the url to which to redirect the customer when the payment completes successfully. Do not rely on this url to capture completed payments. Always confirm payment status with a call to `GET /checkout` or implement webhooks for reliable payment notifications in your application. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify arbitrary additional GET parameters.	null	optional
`.cancelUrl`	string	Specifies the url to which to redirect the customer when he cancels 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 arbitrary additional GET parameters.	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": "XLM",
            "blockchain": "Stellar",
            "network": "STELLAR",
            "relatedAssetId": "XLM:NATIVE",
            "paymentAmount": "9835.1414952",
            "settlement": {
                "assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
                "amount": "1348.547598",
                "netAmount": "1348.547598",
                "fee": "0"
            }
        },
        {
            "assetCode": "BTC",
            "blockchain": "Bitcoin",
            "network": "BITCOIN",
            "relatedAssetId": "BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
            "paymentAmount": "0.0457181",
            "settlement": {
                "assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
                "amount": "1348.547598",
                "netAmount": "1348.547598",
                "fee": "0"
            }
        },
        {
            "assetCode": "ETH",
            "blockchain": "Ethereum",
            "network": "ETHEREUM",
            "relatedAssetId": "ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
            "paymentAmount": "0.7693317",
            "settlement": {
                "assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
                "amount": "1348.547598",
                "netAmount": "1348.547598",
                "fee": "0"
            }
        },
        {
            "assetCode": "LTC",
            "blockchain": "Litecoin",
            "network": "LITECOIN",
            "relatedAssetId": "LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP",
            "paymentAmount": "23.3425586",
            "settlement": {
                "assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
                "amount": "1348.547598",
                "netAmount": "1348.547598",
                "fee": "0"
            }
        }
   ]
}

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	The corresponding payment asset code, e.g. `BTC`. Inspect `GET /assets` for a list of possible values.	false
`.blockchain`	string	The blockchain name in plain text.	false
`.network`	string	The payment network identifier as given by `GET /networks`. Use this identifier to select the desired payment network in the next step at `POST /checkout/commit`.	false
`.relatedAssetId`	string	An asset id as given by `GET /assets`. This asset identifies the Stellar SEP-6 anchor used for capturing the payment, if applicable.	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. The quote is valid for 60 minutes.	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 the selected network identifier 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":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

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 a networkId 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": "XLM",
            "blockchain": "Stellar",
            "network": "STELLAR",
            "relatedAssetId": "XLM:NATIVE",
            "paymentAmount": "9835.1414952",
            "settlement": {
                "assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
                "amount": "1348.547598",
                "netAmount": "1348.547598",
                "fee": "0"
            }
        },
        {
            "assetCode": "BTC",
            "blockchain": "Bitcoin",
            "network": "BITCOIN",
            "relatedAssetId": "BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
            "paymentAmount": "0.0457181",
            "settlement": {
                "assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
                "amount": "1348.547598",
                "netAmount": "1348.547598",
                "fee": "0"
            }
        },
        {
            "assetCode": "ETH",
            "blockchain": "Ethereum",
            "network": "ETHEREUM",
            "relatedAssetId": "ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
            "paymentAmount": "0.7693317",
            "settlement": {
                "assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
                "amount": "1348.547598",
                "netAmount": "1348.547598",
                "fee": "0"
            }
        },
        {
            "assetCode": "LTC",
            "blockchain": "Litecoin",
            "network": "LITECOIN",
            "relatedAssetId": "LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP",
            "paymentAmount": "23.3425586",
            "settlement": {
                "assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
                "amount": "1348.547598",
                "netAmount": "1348.547598",
                "fee": "0"
            }
        }
   ]
}

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 depositNetwork 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",
  "network":"ETHEREUM"
}

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":{
      "assetCode":"ETH",
      "blockchain":"Ethereum",
      "network":"ETHEREUM",
      "amount":"0.0056804",
      "address":"0xc85eBb197c8212C09B7d0905C3ce9e3fCe324F0B",
      "memo":null,
      "memoType":null
   },
   "settlement": {
       "assetId": "USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX",
       "amount": "19.2514345"
   },
   "expirationTime":"2020-02-26T18:49:33+00:00",
   "checkoutId":"29d030183ce9"
}

When you customer selects a network *other than* STELLAR, then the relevant fields to make payment are address and amount. The response fields for memo and memoType are only relevant for payments on STELLAR.

Example Success Response for XLM application/json

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

When your customers select STELLAR 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.

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	The selected payment asset code, e.g. `BTC`, `ETH`, `XLM`, or `LTC`.	false
`.network`	string	The selected payment network as given by `GET /networks`.	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":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

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. You can modify their appearance to match your corporate identity by using Brand Connect.

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":{
      "billingCurrency":"EUR",
      "lineItems":[
         {
            "description":"PCI Graphics Card",
            "netAmount":169.99
         }
      ]
   },
   "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

Explanation of Above Payload Configuration

Above is the minimal configuration required to initiate a checkout. The charge is denominated in EUR and has exactly one line item at a cost of 169.99 EUR. The payment amount charged to by your customer in his crypto of choice is calculated against the total billing amount specified here.

Example Payload (Full)

{
   "charge":{
      "customerId":"716dad4c5e5f",
      "billingCurrency":"USD",
      "lineItems":[
         {
            "description":"PCI Graphics Card",
            "netAmount":199,
            "quantity":1,
            "productId":"P1234"
         }
      ],
      "discountItems":[
         {
            "description":"Loyalty Discount",
            "netAmount":5
         }
      ],
      "shippingCostItems":[
         {
            "description":"Shipping and Handling",
            "netAmount":3.99,
            "taxable":false
         }
      ],
      "taxItems":[
         {
            "name":"Sales Tax",
            "percent":0.0825
         }
      ]
   },
   "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
   "checkoutLanguage":"en",
   "webhook":"https://www.your-server.com/path/to/webhook",
   "pageSettings":{
      "returnUrl":"https://www.merchant.com/path/to/complete/checkout",
      "cancelUrl":"https://www.merchant.com/path/to/cancel/checkout",
      "shopName":"The T-Shirt Store Ltd.",
      "displayBuyerInfo":true,
      "displaySellerInfo":true
   },
   "meta":{
      "customAttribute":"customValue"
   },
   "anchors":{
      "BITCOIN":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
      "ETHEREUM":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR"
   }
}

Request Params (POST)

PRO Tip #1 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 #2 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
`.billingCurrency`	string	A currency code as given by `GET /currencies`. This is the customer facing billing currency quoted on the payment page in hosted checkouts and on invoices. Blockchain payment amounts are calculated against the billing currency and total amount specified in the charge. This is not the payment currency. Your customers will get to choose their preferred blockchain to make payment in their available asset regardless of the currency you specify here.	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`	numeric	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
`.settlementAsset`	string	An asset id as given by `GET /assets`. Specifies the asset you will be credited in when the checkout completes. Set to `ORIGIN` to get credited in the asset your customer pays in without any type of currency conversion.	ORIGIN	optional
`.checkoutLanguage`	string	A language code as given by `GET /languages`. 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`	en	optional
`.webhook`	string	A webhook URL on your server that listens for related checkout events as specified in webhook concepts.	null	optional
`.anchors{}`	object	An advanced setting to declare preferred Stellar SEP-0006 anchors to use during the checkout process. An object containing key value pairs, with the key being a network id as given by `GET /networks` and the value being an anchored asset id as given by `GET /assets`.	null	optional
`.pageSettings{}`	object	An object containing display settings for the customer facing hosted checkout page. Values provided here override your global account settings (if any).	null	optional
`.returnUrl`	string	Specifies the url to which to redirect the customer when the payment completes successfully. Do not rely on this url to capture completed payments. Always confirm payment status with a call to `GET /checkout` or implement webhooks for reliable payment notifications in your application. The checkout `id`, as given in above response, is automatically appended as GET parameter `checkoutId` to facilitate mapping in your application. You can specify arbitrary additional GET parameters.	null	optional
`.cancelUrl`	string	Specifies the url to which to redirect the customer when he cancels 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 arbitrary additional GET parameters.	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": "XLM",
            "blockchain": "Stellar",
            "network": "STELLAR",
            "relatedAssetId": "XLM:NATIVE",
            "paymentAmount": "9835.0578507",
            "settlement": {
                "assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
                "amount": "1348.5361725",
                "netAmount": "1348.5361725",
                "fee": "0"
            }
        },
        {
            "assetCode": "BTC",
            "blockchain": "Bitcoin",
            "network": "BITCOIN",
            "relatedAssetId": "BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
            "paymentAmount": "0.0457177",
            "settlement": {
                "assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
                "amount": "1348.5361725",
                "netAmount": "1348.5361725",
                "fee": "0"
            }
        },
        {
            "assetCode": "ETH",
            "blockchain": "Ethereum",
            "network": "ETHEREUM",
            "relatedAssetId": "ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
            "paymentAmount": "0.7693252",
            "settlement": {
                "assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
                "amount": "1348.5361725",
                "netAmount": "1348.5361725",
                "fee": "0"
            }
        },
        {
            "assetCode": "LTC",
            "blockchain": "Litecoin",
            "network": "LITECOIN",
            "relatedAssetId": "LTC:GC5LOR3BK6KIOK7GKAUD5EGHQCMFOGHJTC7I3ELB66PTDFXORC2VM5LP",
            "paymentAmount": "23.3424109",
            "settlement": {
                "assetId": "USDT:GCQTGZQQ5G4PTM2GL7CDIFKUBIPEC52BROAQIAPW53XBRJVN6ZJVTG6V",
                "amount": "1348.5361725",
                "netAmount": "1348.5361725",
                "fee": "0"
            }
        }
      }
   ]
}

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	The asset code of the payment currency, e.g. `BTC`.	false
`.blockchain`	string	The payment blockchain name in plain text.	false
`.network`	string	The payment network identifier as given by `GET /networks`.	false
`.relatedAssetId`	string	An asset id as given by `GET /assets`. This asset identifies the Stellar SEP-6 anchor used for capturing the payment, if applicable.	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":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

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",
      "sourceNetwork":"ETHEREUM",
      "sourceNetworkName":"Ethereum",
      "depositAddress":"0xA2Bf179E09C503262E418FC72261837726f68F36",
      "blockchainTransactions":[
         {
            "type":"ORIGIN",
            "typeDescription":"Blockchain payment transaction initiated by customer.",
            "network":"ETHEREUM",
            "networkName":"Ethereum",
            "timestamp":"2020-09-16T21:34:32+00:00",
            "tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
            "amount":"0.0069518",
            "amountAssetCode":"ETH",
            "exception":null
         },
         {
            "type":"TRANSFER",
            "typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
            "network":"STELLAR",
            "networkName":"Stellar",
            "timestamp":"2020-09-16T21:34:37+00:00",
            "tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
            "amount":"0.0069518",
            "amountAssetCode":"ETH",
            "exception":null
         },
         {
            "type":"SETTLEMENT",
            "typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
            "network":"STELLAR",
            "networkName":"Stellar",
            "timestamp":"2020-09-16T21:34:42+00:00",
            "tx":"63dab32ba979e41e43a718aaf51c61cadf6dec944715d9fd04f1f61d9ee8800f",
            "amount":"10.0000000",
            "amountAssetCode":"USD",
            "exception":null
         }
      ],
      "payload":{
         "charge":{
            "lineItems":[
               {
                  "description":"T-Shirt",
                  "quantity":"1",
                  "netAmount":"10",
                  "productId":"yellow"
               }
            ],
            "billingCurrency":"USD",
            "customerId":"a2df67b61725"
         },
         "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
      }
   }
}

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`, `RESOLVED_REFUNDED`, `RESOLVED_OTHER`.	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 as given by `GET /assets` that 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. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method 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 Stellar representation of the source asset as given by `GET /assets`. Indicates the payment asset selected by your customer. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceAmountRequired`	string	Indicates the total amount payable by the customer to complete this checkout. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceAmountReceived`	string	The total amount paid by the customer so far. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceNetwork`	string	A payment network id as given by (`GET /networks`). Indicates the payment network selected by the customer in English plain text. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceNetworkName`	string	The selected network name in English plain text.	true
`.depositAddress`	string	The deposit address associated with this checkout. This field is null for checkouts in `PENDING_CHARGE` state. For checkouts on Stellar this field combines the memo, memo type, and account in the following format: `{memo}:{memoType}@{stellarAccount}`	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
`.network`	string	The network id as given by (`GET /networks`). Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on COINQVEST.	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":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

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":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "settlementAmountRequired":"10.0000000",
         "settlementAmountReceived":"10.0000000",
         "settlementAmountFeePaid": "0",
         "sourceAssetId":"ETH:GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR",
         "sourceAmountRequired":"0.0069518",
         "sourceAmountReceived":"0.0069518",
         "sourceNetwork": "ETHEREUM",
         "sourceNetworkName": "Ethereum",
         "depositAddress": "0xA2Bf179E09C503262E418FC72261837726f68F36",
         "blockchainTransactions":[
            {
               "type":"ORIGIN",
               "typeDescription":"Blockchain payment transaction initiated by customer.",
               "network": "ETHEREUM",
               "networkName": "Ethereum",
               "timestamp": "2020-09-16T21:34:32+00:00",
               "tx":"0x02f45bce7e17acca417591018322bbf3721a1849cee2bbc9dfdcb526b2ba4a4f",
               "amount":"0.0069518",
               "amountAssetCode":"ETH",
               "exception":null
            },
            {
               "type":"TRANSFER",
               "typeDescription":"Asset issuer fund transfer from native blockchain to Stellar Network.",
               "network": "STELLAR",
               "networkName": "Stellar",
               "timestamp": "2020-09-16T21:34:37+00:00",
               "tx":"1c1ba2bc2504c3081ce4bf0f51ec1792e919aded6fc178b112ac4393e7f2ab6a",
               "amount":"0.0069518",
               "amountAssetCode":"ETH",
               "exception":null
            },
            {
               "type":"SETTLEMENT",
               "typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
               "network": "STELLAR",
               "networkName": "Stellar",
               "timestamp": "2020-09-16T21:34:42+00:00",
               "tx":"63dab32ba979e41e43a718aaf51c61cadf6dec944715d9fd04f1f61d9ee8800f",
               "amount":"10.0000000",
               "amountAssetCode":"USD",
               "exception":null
            }
         ],
         "payload":{
            "charge":{
               "lineItems":[
                  {
                     "description":"T-Shirt",
                     "quantity":"1",
                     "netAmount":"10",
                     "productId":"yellow"
                  }
               ],
               "billingCurrency":"USD",
               "customerId":"a2df67b61725"
            },
            "settlementAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
         }
      }
   ]
}

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`, `RESOLVED_REFUNDED`, `RESOLVED_OTHER`.	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 as given by `GET /assets` that 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. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method 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 Stellar representation of the source asset as given by `GET /assets`. Indicates the payment asset selected by your customer. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceAmountRequired`	string	Indicates the total amount payable by the customer to complete this checkout. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceAmountReceived`	string	The total amount paid by the customer so far. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceNetwork`	string	A payment network id as given by (`GET /networks`). Indicates the payment network selected by the customer in English plain text. This field is null if the checkout state is `PENDING_CHARGE` and the customer did not select a payment method yet.	true
`.sourceNetworkName`	string	The selected network name in English plain text.	true
`.depositAddress`	string	The deposit address associated with this checkout. This field is null for checkouts in `PENDING_CHARGE` state. For checkouts on Stellar this field combines the memo, memo type, and account in the following format: `{memo}:{memoType}@{stellarAccount}`	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
`.network`	string	The network id as given by (`GET /networks`). Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on COINQVEST.	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":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Error Response Params

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

GET/walletsprotected

Returns a list of wallet objects containing information about the associated asset, balance, available networks, and deposit addresses (if available).

Request

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

Success Response application/json

{
   "wallets":[
      {
         "asset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "balance":"14.7821901",
         "currencyCode":"BTC",
         "networks":[
            {
               "network":"BITCOIN",
               "address":"3QdzvaD2pfKEkqguxAfXW274TUJMtiXqG3"
            },
            {
               "network":"STELLAR",
               "address":"dd376139586eda:text@GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ"
            }
         ]
      },
      {
         "asset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "balance":"17141.2245316",
         "currencyCode":"USD",
         "networks":[
            {
               "network":"STELLAR",
               "address":"dd376139586eda:text@GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ"
            },
            {
               "network":"SWIFT",
               "address":"Use the web app to obtain deposit instructions for bank account deposits."
            },
            {
               "network":"SEPA",
               "address":"Use the web app to obtain deposit instructions for bank account deposits."
            }
         ]
      },
      {
         "asset":"XLM:NATIVE",
         "balance":"89471.2050728",
         "currencyCode":"XLM",
         "networks":[
            {
               "network":"STELLAR",
               "address":"dd376139586eda:text@GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ"
            }
         ]
      }
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`.wallets[]`	array	A list objects, representing the wallets in your account.	false
`.asset`	string	The asset identifier as given by `GET /assets`.	false
`.balance`	string	The asset balance in your wallet.	false
`.currencyCode`	string	The asset's normalized currency code as given by `GET /currencies`.	false
`.networks[]`	array	A list of networks with your wallet deposit addresses. Network identifiers as given by `GET /networks`. This list also indicates to which networks the asset can be transferred to.	false
`.network`	string	The network as given by `GET /networks`.	false
`.address`	string	Your custom deposit address on the blockchain given in `network` (if available). In the case of `STELLAR` the deposit address includes the mandatory memo in the format `memo:memo-type@address`. Please parse accordingly. In the case of `LIGHTNING` deposits can only be initiated via the `POST /deposit-address` endpoint. No custom deposit address currently available for a network if this field is `null`.	true

Error Response application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Error Response Params

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

GET/walletprotected

Returns a wallet object containing information about the associated asset, balance, available networks, and deposit addresses (if available).

Request

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

Request Params

Key	Type	Description	Default	Mandatory
`asset`	string	An asset identifier as given by `GET /assets` or `GET /wallets`.	-	mandatory

Success Response application/json

{
   "wallet":{
      "asset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "balance":"14.7821901",
      "currencyCode":"BTC",
      "networks":[
         {
            "network":"BITCOIN",
            "address":"3QdzvaD2pfKEkqguxAfXW274TUJMtiXqG3"
         },
         {
            "network":"STELLAR",
            "address":"sd376139586eda:text@GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ"
         }
      ]
   }
}

Success Response Attributes

Name	Type	Description	Nullable
`.wallet{}`	array	An object containing information about the wallet.	false
`.asset`	string	The asset identifier as given by `GET /assets`.	false
`.balance`	string	The asset balance in your wallet.	false
`.currencyCode`	string	The asset's normalized currency code as given by `GET /currencies`.	false
`.networks[]`	array	A list of networks with your wallet deposit addresses. Network identifiers as given by `GET /networks`. This list also indicates to which networks the asset can be transferred to.	false
`.network`	string	The network as given by `GET /networks`.	false
`.address`	string	Your custom deposit address on the blockchain given in `network` (if available). In the case of `STELLAR` the deposit address includes the mandatory memo in the format `memo:memo-type@address`. Please parse accordingly. In the case of `LIGHTNING` deposits can only be initiated via the `POST /deposit-address` endpoint. No custom deposit address currently available for a network if this field is `null`.	true

Error Response application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Error Response Params

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

POST/deposit-addressprotected

Creates your blockchain or bank deposit address for a given network and asset.

Request

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

Where payload.json is a JSON object.

Example: Obtaining a Bitcoin deposit address.

{
   "network":"BITCOIN"
}

Returns a deposit address on the Bitcoin network. Your account is credited after one to six blockchain confirmations (depending on the size of the deposit).

Example: Obtaining a USDC deposit address on the Stellar Network.

{
   "network":"STELLAR",
   "asset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
}

Returns a USDC deposit account on the Stellar network. Your account is credited after one blockchain confirmation (within seconds).

Example: Obtaining a BOLT11 Lightning invoice.

{
   "network":"LIGHTNING",
   "amount":"5000"
}

Returns a BOLT11 Lightning invoice for a total amount of 5,000 SAT. Your account is credited after one blockchain confirmation (within seconds).

Request Params

Key	Type	Description	Default	Mandatory
`network`	string	Network identifier as given by `GET /networks`, e.g. `BITCOIN`, `LITECOIN`, `LIGHTNING`, or `STELLAR`. Use the web app to obtain deposit information for bank deposits.	null	mandatory
`asset`	string	Optional asset identifier as given by `GET /assets`. This param is only required when making deposit to multi-asset networks (e.g. Stellar).	network default	optional
`amount`	string	Desired deposit amount for BOLT11 Lightning invoices. This param is only required when making payment via the Lightning network; omit otherwise.	null	optional
`webhook`	string	URL on your server listening for deposits via `WEBHOOK deposit-completed`. Overwrites previously submitted URLs and overrides webhook URL API Settings in the UI (if any).	null	optional

Success Response application/json

{
   "network":"BITCOIN",
   "address":"3QdzvaD2pfKEkqguxAfXW274TUJMtiXqG4",
   "asset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
   "webhook":"https://www.your-server.com/path/to/webhook"
}

Success Response Attributes

Name	Type	Description	Nullable
`network`	string	A network identifier as given by `GET /networks`, e.g. `BITCOIN`, `LITECOIN`, `LIGHTNING`, or `STELLAR`.	false
`address`	string	Make payment to this deposit address. When using the Stellar network to make deposit a mandatory memo is encoded in the format `memo:memo-type@stellar-account`. Parse accordingly.	true
`asset`	string	An asset identifier as given by `GET /assets`.	false
`webhook`	string	The webhook URL on your server to which COINQVEST posts callback notifications during events related to this deposit address (as specified in webhook concepts).	true

Error Response application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

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)	Blockchain transaction id of your deposit or unique identifier as given by `GET /deposits`.	null	mandatory

Success Response application/json

{
   "deposit":{
      "id":"eb3729168fb2",
      "state":"COMPLETED",
      "timestamp":"2022-10-14T19:49:51+00:00",
      "network":"BITCOIN",
      "networkName":"Bitcoin",
      "depositAddress":"bc1q2acmt0h28k0n5zlazj2m8k3zwxaklzpcx0kf34",
      "asset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
      "currencyCode":"BTC",
      "amountGross":"7.1479281",
      "amountNet":"7.1479281",
      "amountFees":"0.0000000",
      "webhook":"https://www.your-server.com/path/to/webhook",
      "customerId":null,
      "blockchainTransactions":[
         {
            "type":"DEPOSIT_ORIGIN",
            "typeDescription":"Blockchain transaction on the source network.",
            "network":"BITCOIN",
            "networkName":"Bitcoin",
            "timestamp":"2022-10-14T20:00:17+00:00",
            "tx":"77ddc93467f12fc79d73a936f09044689eebb1e045c1f81b5c14a91396147fed",
            "amount":"7.1479281",
            "amountAssetCode":"BTC"
         },
         {
            "type":"DEPOSIT_SETTLEMENT",
            "typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
            "network":"STELLAR",
            "networkName":"Stellar",
            "timestamp":"2022-10-14T20:00:17+00:00",
            "tx":"24c69c410e48ab3f7dd264429ec090e954b3b8b3b9860a5dd6c130f2926e0857",
            "amount":"7.1479281",
            "amountAssetCode":"BTC"
         }
      ]
   }
}

Success Response Attributes

Name	Type	Description	Nullable
`.deposit{}`	object	An object containing deposit information.	false
`.id`	string(12)	Unique identifier of this deposit.	false
`.state`	string	The deposit state. Possible values: `COMPLETED`, `FAILED`, `PROCESSING`, `PENDING_EXTERNAL`	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was first detected.	false
`.network`	string	A payment network id as given by `GET /networks`. Indicates the payment network on which the deposit was made.	false
`.networkName`	string	The payment network name in English plain text.	false
`depositAddress`	string	The deposit address to which the payment was made. When using the Stellar Network the memo is encoded in the format `memo:memo-type@stellar-account`. Parse accordingly.	false
`.asset`	string	The Stellar representation of the asset credited to your account as given by `GET /assets`.	false
`.currencyCode`	string	The deposit currency code as given by `GET /currencies`.	false
`.amountGross`	string	The gross amount credited to your account.	false
`.amountNet`	string	The net amount credited to your account. These funds are instantly available for withdrawal.	false
`.amountFees`	string	The paid fees, if any.	false
`.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
`.customerId`	string(12)	The customer id associated with this deposit, if any.	true
`.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) 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
`.network`	string	The network id as given by (`GET /networks`). Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on COINQVEST.	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":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

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":1,
   "limit":10,
   "offset":0,
   "deposits":[
      {
         "id":"eb3729168fb2",
         "state":"COMPLETED",
         "timestamp":"2022-10-14T19:49:51+00:00",
         "network":"BITCOIN",
         "networkName":"Bitcoin",
         "depositAddress":"bc1q2acmt0h28k0n5zlazj2m8k3zwxaklzpcx0kf34",
         "asset":"BTC:GCQVEST7KIWV3KOSNDDUJKEPZLBFWKM7DUS4TCLW2VNVPCBGTDRVTEIT",
         "currencyCode":"BTC",
         "amountGross":"7.1479281",
         "amountNet":"7.1479281",
         "amountFees":"0.0000000",
         "webhook":"https://www.your-server.com/path/to/webhook",
         "customerId":null,
         "blockchainTransactions":[
            {
               "type":"DEPOSIT_ORIGIN",
               "typeDescription":"Blockchain transaction on the source network.",
               "network":"BITCOIN",
               "networkName":"Bitcoin",
               "timestamp":"2022-10-14T20:00:17+00:00",
               "tx":"77ddc93467f12fc79d73a936f09044689eebb1e045c1f81b5c14a91396147fed",
               "amount":"7.1479281",
               "amountAssetCode":"BTC"
            },
            {
               "type":"DEPOSIT_SETTLEMENT",
               "typeDescription":"Stellar transaction crediting your COINQVEST merchant account.",
               "network":"STELLAR",
               "networkName":"Stellar",
               "timestamp":"2022-10-14T20:00:17+00:00",
               "tx":"24c69c410e48ab3f7dd264429ec090e954b3b8b3b9860a5dd6c130f2926e0857",
               "amount":"7.1479281",
               "amountAssetCode":"BTC"
            }
         ]
      }
   ]
}

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
`.state`	string	The deposit state. Possible values: `COMPLETED`, `FAILED`, `PROCESSING`, `PENDING_EXTERNAL`	false
`.timestamp`	timestamp	W3C formatted time stamp with time zone (UTC) specifying when the deposit was first detected.	false
`.network`	string	A payment network id as given by `GET /networks`. Indicates the payment network on which the deposit was made.	false
`.networkName`	string	The payment network name in English plain text.	false
`depositAddress`	string	The deposit address to which the payment was made. When using the Stellar Network the memo is encoded in the format `memo:memo-type@stellar-account`. Parse accordingly.	false
`.asset`	string	The Stellar representation of the asset credited to your account as given by `GET /assets`.	false
`.currencyCode`	string	The deposit currency code as given by `GET /currencies`.	false
`.amountGross`	string	The gross amount credited to your account.	false
`.amountNet`	string	The net amount credited to your account. These funds are instantly available for withdrawal.	false
`.amountFees`	string	The paid fees, if any.	false
`.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
`.customerId`	string(12)	The customer id associated with this deposit, if any.	true
`.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) 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
`.network`	string	The network id as given by (`GET /networks`). Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on COINQVEST.	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":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

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 USDC into BTC)

{
   "sourceAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
   "sourceAmount":100,
   "targetAsset":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF"
}

Above example requests a swap of 100 USDC 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:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF",
   "targetAsset":"XLM:NATIVE",
   "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	An asset identifier as given by `GET /assets`. Specifies the source asset in the swap.	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	An asset identifier as given by `GET /assets`. Specifies the target asset in the swap.	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",
      "sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "sourceAmount":"100.0000000",
      "targetAssetId":"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
`.sourceAssetId`	string	The source asset in the swap. An asset id as given by `GET /assets`.	false
`.sourceAmount`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account on swap completion.	false
`.targetAssetId`	string	The target asset in the swap. An asset id as given by `GET /assets`.	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
`.network`	string	The network id as given by (`GET /networks`). Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on COINQVEST.	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":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

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.

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",
      "sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "sourceAmount":"100.0000000",
      "targetAssetId":"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.",
           "network": "STELLAR",
           "networkName": "Stellar",
           "timestamp": "2021-05-06T22:16:01+00:00",
           "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
`.sourceAssetId`	string	The source asset in the swap. An asset id as given by `GET /assets`.	false
`.sourceAmount`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account on swap completion.	false
`.targetAssetId`	string	The target asset in the swap. An asset id as given by `GET /assets`.	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
`.network`	string	The network id as given by (`GET /networks`). Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on COINQVEST.	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":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

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",
      "sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "sourceAmount":"100.0000000",
      "targetAssetId":"XLM:NATIVE",
      "targetAmount":"243.3928192",
      "blockchainTransactions":[
        {
           "type":"SWAP",
           "typeDescription":"Blockchain transaction executed during the swap on the Stellar Network.",
           "network": "STELLAR",
           "networkName": "Stellar",
           "timestamp": "2021-05-06T22:16:01+00:00",
           "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
`.sourceAssetId`	string	The source asset in the swap. An asset id as given by `GET /assets`.	false
`.sourceAmount`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account on swap completion.	false
`.targetAssetId`	string	The target asset in the swap. An asset id as given by `GET /assets`.	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
`.network`	string	The network id as given by (`GET /networks`). Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on COINQVEST.	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":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

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",
            "sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "sourceAmount":"10.0000000",
            "targetAssetId":"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",
            "sourceAssetId":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "sourceAmount":"100.0000000",
            "targetAssetId":"XLM:NATIVE",
            "targetAmount":"243.3928192",
            "blockchainTransactions":[
               {
                  "type":"SWAP",
                  "typeDescription":"Blockchain transaction executed during the swap on the Stellar Network.",
                  "network": "STELLAR",
                  "networkName": "Stellar",
                  "timestamp": "2021-05-06T22:16:01+00:00",
                  "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
`.sourceAssetId`	string	The source asset in the swap. An asset id as given by `GET /assets`.	false
`.sourceAmount`	string	A numeric string indicating the total amount of `sourceAsset` debited from your account on swap completion.	false
`.targetAssetId`	string	The target asset in the swap. An asset id as given by `GET /assets`.	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
`.network`	string	The network id as given by (`GET /networks`). Indicates where this transaction was executed.	false
`.networkName`	string	The network name in English plain text.	false
`.timestamp`	string	The timestamp at which this transaction was registered on COINQVEST.	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":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

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":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
   "sourceAmount":10,
   "targetNetwork":"STELLAR",
   "targetAsset":"XLM:NATIVE",
   "targetAccount":{
      "account":"GASKYWPPQ2VSO6KNIPIRVXMSSDGZLYZQ67CDTLVXOXYDG26SPZ66EDCQ",
      "memo":"EXODUS",
      "memoType":"text"
   }
}

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

Example Payload (Withdrawal to the Bitcoin Network)

{
   "sourceAsset":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
   "sourceAmount":100,
   "targetNetwork":"BITCOIN",
   "targetAccount":{
      "address":"bc1qj633nx575jm28smgcp3mx6n3gh0zg6ndr0ew23"
   },
   "anchor":"BTC:GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF"
}

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 anchor BTC:GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5 to process this payment and convert the funds from their Stellar representation on COINQVEST into native Bitcoin. See GET /assets for available asset.

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

{
   "sourceAsset":"BRL:GDVKY2GU2DRXWTBEYJJWSFXIGBZV6AZNBVVSUHEPZI54LIS6BA7DVVSP",
   "sourceAmount":10000,
   "targetNetwork":"PIX",
   "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 Specifies the network to which you want to withdraw. This field takes a network id as given by given by GET /networks. false mandatory

.targetAsset string This field is only relevant when the targetNetwork is set to STELLAR (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 BITCOIN, ETHEREUM, LITECOIN

address The address to which the withdrawal should be sent.

Field Attributes for withdrawals to LIGHTNING

address A BOLT 11 invoice address without encoded amount. Use an invoice that allows for an arbitrary target amount.

Field Attributes for withdrawals to STELLAR (any Stellar 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`.

Field Attributes for withdrawals to CBU/CVU (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 PIX (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.

false

mandatory

.anchor string A an asset id to optionally declare a specific anchor to process this payment and convert the funds from their Stellar representation on COINQVEST into their native form. See GET /assets for available anchors. true optional

Success Response application/json

{
    "withdrawal": {
        "id": "5ff64e670169",
        "type": "WITHDRAWAL",
        "state": "PENDING_API_COMMIT",
        "origin": "API",
        "timestamp": "2022-06-25T03:24:31+03:00",
        "sourceAssetCode": "USDC",
        "sourceAssetIssuer": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
        "sourceAmount": "2000.0000000",
        "targetAssetCode": "USDC",
        "targetAssetIssuer": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
        "targetAmount": "2000.0000000",
        "fee": "0",
        "targetNetwork": "STELLAR",
        "transactionId": null,
        "targetAccount": {
            "account": "GBFNWESKGTN2GDED3ZF5OI4XKFKCFLMSAU5UUU7YCFNMAYCJLJLGUDCQ",
            "memo": "custom-memo",
            "memoType": "text"
        }
    }
}

Above response is issued in response to a withdrawal request over 2000 USDC to the Stellar Network.

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 asset debited from your account, see GET /assets. 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 The target asset identifier, see GET /assets. false

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

.fee string Mining or third party fees, if any. Your account is debited the equivalent of the sum of
fee + targetAmount. false

.targetNetwork string A network identifier as given by GET /networks). 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 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`.

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).

false

Error Response application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

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": "5ff64e670169",
        "type": "WITHDRAWAL",
        "state": "PENDING_API_COMMIT",
        "origin": "API",
        "timestamp": "2022-06-25T03:24:31+03:00",
        "sourceAssetCode": "USDC",
        "sourceAssetIssuer": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
        "sourceAmount": "2000.0000000",
        "targetAssetCode": "USDC",
        "targetAssetIssuer": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
        "targetAmount": "2000.0000000",
        "fee": "0",
        "targetNetwork": "STELLAR",
        "transactionId": null,
        "targetAccount": {
            "account": "GBFNWESKGTN2GDED3ZF5OI4XKFKCFLMSAU5UUU7YCFNMAYCJLJLGUDCQ",
            "memo": "custom-memo",
            "memoType": "text"
        }
    }
}

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": "5ff64e670169",
        "type": "WITHDRAWAL",
        "state": "COMPLETED",
        "origin": "API",
        "timestamp": "2022-06-25T03:24:31+03:00",
        "sourceAssetCode": "USDC",
        "sourceAssetIssuer": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
        "sourceAmount": "2000.0000000",
        "targetAssetCode": "USDC",
        "targetAssetIssuer": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
        "targetAmount": "2000.0000000",
        "fee": "0",
        "targetNetwork": "STELLAR",
        "transactionId": "1e9c0c0cec0e6d54ed67d0c9f7899e238409c1f053e96fa1d3647bddbfe8b3cf",
        "targetAccount": {
            "account": "GBFNWESKGTN2GDED3ZF5OI4XKFKCFLMSAU5UUU7YCFNMAYCJLJLGUDCQ",
            "memo": "custom-memo",
            "memoType": "text"
        }
    }
}

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 asset debited from your account, see GET /assets. 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 The target asset identifier, see GET /assets. false

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

.fee string Mining or third party fees, if any. Your account is debited the equivalent of the sum of
fee + targetAmount. false

.targetNetwork string References the network to which this withdrawal was sent by id and as originally given in the request. See GET /networks) for more. 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 targetNetwork.

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`.

Field Attributes for withdrawals to ARS

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

Field Attributes for withdrawals to PIX

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

false

Error Response application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

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",
      "targetNetwork":"NIBSS",
      "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

.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 The asset id debited from your account, see GET /assets. 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 The target asset identifier, see GET /assets. 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

.targetNetwork string A network identified as given by GET /networks). true

.transactionId string(64) References the payout 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 targetNetwork.

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`.

Field Attributes for withdrawals to ARS

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

Field Attributes for withdrawals to PIX

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

false

Error Response application/json

{
    "errors":[
        "invalid request (and more information explaining the error in plain text)"
    ]
}

Error Response Params

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

GET/withdrawalsprotected

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

Request

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

Request Params

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

Success Response application/json

{
   "count":2,
   "limit":10,
   "offset":0,
   "withdrawals":[
      {
         "id":"b35c97c377f9",
         "type":"WITHDRAWAL",
         "state":"COMPLETED",
         "origin":"UI",
         "timestamp":"2020-03-04T17:22:39+02:00",
         "sourceAssetCode":"XLM",
         "sourceAssetIssuer":"XLM:NATIVE",
         "sourceAmount":"0.1765850",
         "targetAssetCode":"XLM",
         "targetAssetIssuer":"XLM:NATIVE",
         "targetAmount":"0.1765850",
         "withdrawalFee":"0",
         "targetNetwork":"STELLAR",
         "transactionId":"b7bb615cabf971d1e00256ae87249333e4deb9ef1ad5dad80ee2af0ea21d050b",
         "targetAccount":{
            "account":"GDONUHZKLSYLDOZWR2TDW25GFXOBWCCKTPK34DLUVSOMFHLGURX6FNU6",
            "memo":"EXODUS",
            "memoType":"text"
         }
      },
      {
         "id":"12d72c3c8145",
         "type":"WITHDRAWAL",
         "state":"COMPLETED",
         "origin":"UI",
         "timestamp":"2020-03-04T19:54:47+02:00",
         "sourceAssetCode":"USDC",
         "sourceAssetIssuer":"USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
         "sourceAmount":"1.4231566",
         "targetAssetCode":"NGNT",
         "targetAssetIssuer":"NGNT:GAWODAROMJ33V5YDFY3NPYTHVYQG7MJXVJ2ND3AOGIHYRWINES6ACCPD",
         "targetAmount":"315.0909904",
         "withdrawalFee":"200.0000000",
         "targetNetwork":"NIBSS",
         "transactionId":"62070ddf01d98e4cb3dc25e5052810259013df28a9e551d948fa2e1b1757de09",
         "targetAccount":{
            "nuban":"4791494548",
            "bankName":"FirstBank"
         }
      }
   ]
}

Success Response Attributes

Name Type Description Nullable

.count integer The total number of withdrawals sent from this account. false

.limit integer The limit argument used in this request. false

.offset integer The pagination offset used in this request. false

.withdrawals[] array A list of withdrawal objects. false