Skip to content

Orders

Using the Grapes Orders API you can move fiat into digital assets, pay your bills or other businesses and individuals in digital assets or fiat, swap between different digital assets or blockchains. This API serves as your all-in-one solution to move in and out of fiat currency or swap between digital assets and blockchains. Consider this your sommelier course for navigating the world of blockchain payments and FX.

Currently, Orders on Grapes have a fiat leg and a digital asset leg. A purchase on Grapes is when you are purchasing digital assets using fiat. A redemption on Grapes is when you want to redeem digital assets for fiat. Crypto transfers and crypto/blockchain swaps are coming soon. Currently the API endpoints are for crypto on and off ramps (from fiat or back into fiat).

For orders the digital asset leg is called the transaction part of the order and the fiat transfer leg is the transfer part of the order. For orders you must specify the banking details for the fiat leg of the transaction using the appropriate banking details ID. 

POST /orders/purchase 
POST /orders/redeem  
GET /orders
GET /orders/order 
GET /orders/FXrate

The endpoints are described in more detail as follows. This documentation is a high-level summary and is meant to be read in conjunction with the swagger documentation.

POST /orders/purchase

This endpoint is used to create a purchase order. A purchase order is defined as buying digital assets using CAD (FIAT). Currently, QCAD or USDC can be purchased using CAD. For purchase orders the cryptoAmount must be specified as well as the fiatCurrency and the asset. The fiatAmount, fxRate and fxRateTimeStamp are autocalculated (to see Grapes' rates, please use the fxRate endpt to fetch the indicative buy/sell rates). For purchase orders, only Electronic Funds Transfer (EFT) and Interac E-TRANSFER are supported currently (BILL_PAY and WIRE coming soon). The bankingDetailsId is the banking information for where you would like to withdraw the fiat to or purchase the crypto from. The bankingDetailsId must be banking information associated with the business/Grapes' user. Grapes does not support third-party purchases.

In the example request body below, 10 QCAD is being purchased with CAD. The CAD is being withdrawn from details under bankingDetailsId=2. The Grapes user is "Test User" and the banking details are associated with the user. The wallet address also belongs to the registered Grapes user.

The flow for purchases is as follows. The purchase order is created. A transfer is created for the fiat leg of the transaction, which involves the Electronic Funds Transfer (EFT) withdrawal from the customer's account. Simultaneously, a transaction is created for the digital asset leg of the transaction. The status of both the transfer and transaction object is set to initiated. Upon successful settlement of the fiat leg, i.e fiat funds received, the status of the transfer is set to PROCESSED, the referenceID is updated, and the digital asset leg of the transaction will begin. Once the digital assets have been transferred, the transaction status is set to PROCESSED, indicating the completion of the purchase order.

Partial Response Body Example:

{
  "fiatAmount": 10,
  "cryptoAmount": 10,
  "fxRate": 1,
  "fxRateTimestamp": "2023-05-15T18:22:08.464Z",
  "address": "HEVMQGGDUVZ53AUHAY2FXPO4OVM7T5DPX7IPCNZO7LOSSEUKIVEKU4D72A",
  "chain": "ALGORAND",
  "asset": "QCAD",
  "fiatCurrency": "CAD",
  "paymentMethod": "EFT",
  "firstName": "Test",
  "lastName": "User",
  "bankingDetailsId": 2,
  "attestation": 1,
  "completeLater": true,
  "type": "PURCHASE",
  .......
}

POST /orders/redeem

This endpoint is used to create a redeem order which is defined as redeeming digital assets to CAD (FIAT). You can 'redeem' to your own bank account (the account associated with the Grapes' user) or you can also 'redeem' or 'send' to a third-party bank account (by entering banking details for a contact using the Contacts endpoint). To redeem to a third-party bank account, please use "FIAT_OTHER" as the payment method (FIAT_OTHER signifies this is a third-party payout). The redeem endpoint requires a request body with the details of the order to be created. Upon successful creation of the redeem order, a response containing the order details is returned.

The flow for a redemption (from a custodial wallet or 'Grapes' wallet) is as follows. The redemption order is created. A transaction is created for the digital asset leg of the transaction, the assets will be withdrawn from the user's wallet. Simultaneously, a transfer is created for the fiat leg of the transaction, in this case this is the EFT transfer of funds to the user's bank account once the digial assets have been received. The status of both the transfer and transaction object is set to initiated. Upon successful completion of the blockchain transfer, i.e digital assets received, the status of the transaction is set to PROCESSED, the referenceID is updated with the blockchain hash, and the second leg, the fiat transfer leg - the transfer will begin. Once the fiat has been transferred to the user's bank account, the transfer status is set to PROCESSED, the referenceID is recorded, indicating the completion of the redemption order.

GET /orders

This endpoint is used to query orders based on specific parameters such as type, status, chain, asset, fiatcurrency, and sortBy. This endpoint returns a response containing the queried orders. You can see the format below of a purchase order. The order object records the transaction, the transfers records the fiat leg and the transactions records the blockchain leg.

Parameters:

  • type: This is the order type.

  • Available values: PURCHASE, REDEEM

  • status: This is the order status.

  • Available values: NEW, INITIATED, PROCESSED, CANCELLED, QUEUED, EXPIRED, DECLINED, FAILED, INCORRECT_RECIPIENT

  • chain: These are the supported blockchains.

  • Available values: ALGORAND, STELLAR, ETHEREUM

  • asset: These are the supported assets - please exclude VCAD.

  • Available values: VCAD, QCAD, USDC

  • fiatCurrency: These are the supported fiat currencies - USD coming soon.

  • Available values: CAD, USD

  • sortBy: Sort the results.

  • Available values: NEWEST, OLDEST, HIGHEST, LOWEST

  • page: Page number.

Response Body example:

{
  "numofPages": 1,
  "orders": [
    {
      "id": 1,
      "type": "PURCHASE",
      "fiatAmount": 10,
      "fiatCurrency": "CAD",
      "cryptoAmount": 10,
      "fxRate": 1,
      "fxRateTimeStamp": "2023-05-15T18:22:08.464Z",
      "status": "INITIATED",
      "paymentMethod": "EFT",
      "createdAt": "2023-05-15T18:22:08.464Z",
      "updatedAt": "2023-05-15T18:22:08.464Z",
      "ipAddress": "127.0.0.1",
      "transfers": 
        {
          "id": 1,
          "amount": "10.00",
          "status": "INITIATED",
          "fiatCurrency": "CAD",
          "referenceId": "",
          "bankingDetailsId": "1",
          "createdAt": "2023-05-15T18:22:08.464Z",
          "updatedAt": "2023-05-15T18:22:08.464Z",
          "order": {
            "id": 1
          }
        }
      ,
      "transactions": 
        {
          "id": 1,
          "amount": "10.00",
          "status": "INITIATED",
          "address": "HEVMQGGDUVZ53AUHAY2FXPO4OVM7T5DPX7IPCNZO7LOSSEUKIVEKU4D72A",
          "chain": "ALGORAND",
          "asset": "QCAD",
          "referenceId": "",
          "createdAt": "2023-05-15T18:22:08.464Z",
          "updatedAt": "2023-05-15T18:22:08.464Z",
          "order": {
            "id": 1
          }
        }
    }
  ]
}

GET /orders/order

This endpoint is used to fetch a specific order by ID, rather than fetching all orders. This endpoint requires an order ID as a parameter in the query string. Upon successful retrieval of the order, a response containing the order details is returned (similar to the above response body example shown but for a specific order).

GET /orders/FXrate

This endpoint is used to fetch the USDC/QCAD or USD/QCAD buy/sell exchange rates that Grapes offers. Upon successful retrieval of the exchange rate, a response containing the indicative buy/sell exchange rate is returned. Our exchange rates are also published on our website.