Skip to content

Get started with exchanges

This section introduces a basic test flow to set up and connect a Core Client to perform exchange duties. On the Qredo network, an exchange is represented by its own Qredo user account with Partner API access and a Core Client that is authorized to perform exchange tasks.

Integration with Qredo would allow a third-party service (like a crypto exchange) to offer Qredo custodial wallets to its user base. Note that an exchange is often referred to as a "counterparty" because it is basically a special type of custodian (approver) on the Qredo network and participates in approving transactions of their own users who have Qredo accounts (and specific wallets).

Exchange integration

From an Exchange standpoint, Qredo integration applies to exchange end users who also have Qredo user accounts. These Qredo end users have the option to connect one or more of their Qredo wallets to that exchange. This allows an exchange to link these "connected" Qredo wallets to their exchange accounts. Such wallets must be of type dedicated counterparty or multi-counterparty. A dedicated wallet connects with a single exchange while the multi-counterparty can connect with several.

Exchange wallet types: dedicated vs multi-counterparty
  • Dedicated counterparty wallet - a type of Qredo wallet that connects to a single counterparty (exchange). The end user of the Qredo web app creates a dedicated wallet and selects the counteparty (exchange) from a list. Transactions out of dedicated wallets undergo custody as ever but this time require an exchange approval as well. In other words: every transaction out of a connected wallet undergoes custody, according to the applicable policy; and additionally requires an approval by the exchange. In this way, the Exchange Core Client acts as a master custodian with custodial control over assets in the connected dedicated wallets. This is useful, for example, when the end user may have a limit order open on the exchange side. The exchange must ensure the respective account holds enough available crypto to meet the limit order and this is accomplished with custody.
    If a user attempts to move assets out of the wallet in a way that the remaining balance would be insufficient to fulfil any open positions on the exchange, the exchange can block this transaction. Exchanges are also granted “sweep” rights over the wallet to allow them to fulfil orders without further approval from the user or the user’s approvers.
  • Multi-counterparty wallet - a type of Qredo wallet that connects to one or more counterparties. Unlike a dedicated wallet, the end user of the Qredo web app does not have to select counterparties during wallet creation. Another difference is that the user can connect exchanges to this wallet at any point after creation. The purpose of this wallet is to enable a trader to have multiple market orders placed on different exchanges. This is a non-leveraged wallet and has the same features as a standard wallet. A third party can perform sweep transactions with this wallet, bypassing wallet approvers. Unlike the dedicated wallet, with multi-counterparty wallet, the exchange does not apply additional custody to outbound transfers.

Exchange Core Client duties

The exchange on Qredo is essentially a type of a Core Client that performs the following functions:

  • approve or reject requests to connect Qredo wallets to the exchange.
  • approve or reject sweep transactions initiated by exchanges from any connected wallets.
  • act as a master custodian for connected dedicated wallets.

Basically, using the Exchange Core Client is similar to the regular custodial Core Client. Again, you can connect to the web socket feed. You identify your exchange client using its id and use the same Core Client API resources for approvals and rejections. However, there are a few additional API resources, e.g. for performing sweep transactions.

This section will guide you through the process of setting up your exchange and test out its functionality.

End user's perspective

The Qredo web app end user creates a wallet of type dedicated or multi-counterparty. With a dedicated wallet, they select a counterparty, which is the exchange(s) to connect your wallets to.

This section will guide you through the end user process and the respective interaction with the exchange side.

This example will use a dedicated wallet

A wallet of type dedicated will be used in this example. The multi-counterparty wallet experience is similar from an exchange standpoint.

Overview of steps

In the suggested flow, steps 1 to 3 help you set up your exchange and steps 4 onward present a basic test flow with end user interaction.

  1. Create a Core Client as described in create a Core Client. You will be using it to get your exchange feed.
  2. Set up branding and test accounts: contact Qredo and provide your Exchange Core Client id, plus your exchange name and logo, as well as user metadata and test accounts.
  3. Connect your Exchange Core Client to a web socket and start listening for client activity.
  4. Access the Qredo Web app with a test end user account (from the list provided in step 3) in the Qredo Web app, set up a fund (if you haven't done so already) and create a dedicated wallet to connect.
  5. On the Exchange Core Client, approve the wallet connect request.
  6. From end user account in the Qredo Web app, confirm the wallet is activated.
  7. Perform tests of available actions and websocket feed with the Exchange Core Client.

After you verify that everything described in these steps works as expected, you can proceed to go live with your exchange.

1. Create a Core Client instance

Follow the instructions in the Create and set up a Core Client section to create your Exchange Core Client.

2. Set up branding and test accounts

The branding setup includes all the visual aspects of your exchange in the Qredo web app. Before you go live, send the following data to your Qredo account manager:

  1. id: the id of the Core Client created in the previous step.
  2. Name and logo of your exchange: this is how Qredo users will identify your exchange in the Qredo web app.
  3. User metadata that is needed for connecting Qredo users to the exchange. Currently Qredo supports a customer ID (a unique ID provided to the user by you as an exchange) which can optionally be combined with email address (the address used by the user to register on your exchange platform). The end user will have to supply this metadata each time they create a dedicated or multi-counterparty wallet in the Qredo web app.
  4. Create one or a few Qredo test accounts. Note that your exchange will become available in the Qredo web app after it goes live. Before you're at that stage, you can use test accounts: only they will be able to visualize your exchange in the Qredo web app. Create and register your Qredo user test accounts and provide the Qredo sign-in email addresses.

After you are finalize these steps, send all data to your Qredo account manager so you can move on with the steps that follow.

3. Connect Exchange Core Client to feed

Use your Exchange Core Client id and follow the instructions to connect the Core Client to the websocket feed and start listening for client activity.

The exchange feed follows a format similar to that of the approver Core Client feed.

Your exchange is fully operational now

Once you have successfully completed Step 3 of this tutorial, your exchange is fully functional to perform the relevant operations.

The remaining steps help you test out your exchange alongside the end user experience in the Qredo web app.

4. End user: create a dedicated wallet

In this step, the Qredo user creates a wallet in Qredo Web app of either type: dedicated counterparty.

Use your test account as prepared and provided to Qredo in step 2 and perform the following:

  1. Sign in to the Qredo web app.
  2. Create a fund(if you don't want to use an existing one) and set up a wallet of type dedicated counterparty. If you already have a fund you want to use, simply add a dedicated wallet.
  3. During process of setting up the wallet, select your exchange from the Counterparty drop-down list.
  4. The process will require the end user to enter the required metadata (that the exchange has communicated with the Qredo account manager).
  5. Once The wallet appears as Pending in the Qredo Web app for that account.

Upon completion of this procedure, the Qredo web app sends the exchange a request to connect this dedicated wallet.

5. Exchange: process wallet connection request

On the Exchange Core Client side, you will receive the feed with a pending wallet connection request. The format is similar to the other requests pending custody and is specified by its unique action_id but this time it is of type: ApproveNewWalletConnect

{
  "coreClientID": "6kC7C...Vuz4W",
  "expireTime": 1642766156,
  "id": "<action_id>",
  "status": "pending",
  "timestamp": 1642762556,  
  "type": "ApproveNewWalletConnect"
}

You must approve or reject the connect wallet request before it expires.

User can resubmit Connect wallet request

The end user wallet request for connecting remains in Pending status until approved/rejected by the Exchange Core Client. If the request expires, the user can resubmit the request. They have the option to edit the requested metadata. Obviously, this will result in a new request in your exchange feed.

Get details of a connection request

Use GET /action/{action_id} to retrieve various details of the wallet connection request, including end-user metadata input.

View action details of any status, not just pending

Similarly to the Core Client approver, you can use this API call to view details of any action, regardless of its status, whether approved, rejected, expired or pending.

Example request: GET /action/{action_id}

GET /coreclient/{client_id}/action/{action_id}

Example response: GET /action/{action_id}

The response contains various connection-related data including the end-user metadata input.

{
  "id": "<action id>",
  "coreClientID": "<Exchange Core Client id>",
  "type": "ApproveNewWalletConnect",
  "status": "pending",
  "timestamp": "<timestamp of request submission>",
  "expireTime": "<Epoch timestamp when action expires if not approved/rejected>",
  "details": {
    "clientData": {
      "customer_email": "<Qredo user sign-in email>",
      "customer_id": "<Qredo user ID with Exchange>"
    },
    "wallet": {
      "walletID": "<address of connection request wallet>",
      "name": "Dedicated Eth test - custom policy",
      "asset": "ETH-TESTNET",
      "type": 1,
      "typeCode": "dedicated"
    }
  }
}

Approve connection request

Use PUT /action/{action_id} to approve a pending connection request. A successful response returns a HTTP 200 OK confirmation.

Example request: PUT /action/{action_id}

With this API resource, you pass your Core client_id and action_id as URL parameters. 

PUT /coreclient/{client_id}/action/{action_id}

Example response: PUT /action/{action_id}

The approve response returns HTTP 200 OK.

{"code":200,"msg":"OK"}

Reject connection request

Use DELETE /action/{action_id} to reject a pending connection request. A successful response returns a HTTP 200 OK confirmation. You can only reject actions in pending status.

Example request: DELETE /action/{action_id}

With this API resource, you pass your Core client_id and action_id as URL parameters.

DELETE /coreclient/{client_id}/action/{action_id}

Example response: DELETE /action/{action_id}

The reject response returns HTTP 200 OK.

{"code":200,"msg":"OK"}

The end user will see a relevant message when viewing the respective wallet in the Qredo web app: "Counterparty Request Rejected".

6. End user: confirm that wallet is activated

After approval on the exchange side, the wallet status changes to Active in the Qredo Web app. To confirm that, sign in to the Qredo Web app with your test account and open the fund containing the wallet. After the wallet has been approved, the user can add assets by deposit or transfer in transactions.

7. Test other exchange actions

Use your Exchange Core Client id to perform these API actions with your exchange:

  • Fetch a list of all wallets connected to your exchange:
GET /coreclient/{client_id}/wallets
  • View details of a connected wallet, including assets and balance:
GET /wallet/{wallet_id}
  • View transaction history of a connected wallet:
GET /wallet/{wallet_id}/history
  • Connect to a live feed of connected dedicated wallet transactions by listening to the following websocket feed:
wss://api.qredo.network/api/v1/p/wallets/feed

For more info on Core Client transactions, see approving and rejecting transactions with the Core Client.

You can now go live

If you have completed all steps from above, contact your Qredo account manager and request to go live. When your exchange is live, all Qredo users can choose it when creating a dedicated or multi-party wallet.

Last update: 2022-12-14