Getting Ready For Trading

If you haven’t already gone through the Getting Started article, you’ll want to complete that before carrying on.

Now that you’ve got your Organization and Bank set up in the Partner Portal, it’s time to add a Customer, create your Verification Key, attach an Identity, create an Account, and try out the Quote and Trade API’s.

In the last article we talked about the Organization being the top-level object, and one or more banks belonging to the Organization. Likewise, all downstream objects, including Customers, Accounts and Identity Records belong under Banks. The Customer object is the main data model for each individual customer’s actions; accounts, identity records, quotes and trades all belong to the Customer.

Executing a successful trade for a Customer requires a number of one time setup steps, which we’ll walk through in this guide. At a high level, this is what you’ll be doing:

  1. Use auto-generated RSA Verification Key, or create your own
  2. Creating a Customer
  3. Creating and attaching an Identity Record to the Customer
  4. Creating an Account associated with your Customer
  5. Generating a Quote for your Customer
  6. Executing a Trade against your Quote

Let’s jump in and get you running.

1. Create Verification Key

For convenience, the sandbox environment auto-generates an RSA verification key, allowing you to skip the step of generating your own. The verification key is a public/private key pair that you generate, and subsequently use to sign all Identity Records. The signing of an Identity Record acts as an Attestation of your KYC process for a specific customer.

The auto-generated verification private key is:

Saving this key as a local file named verification_key.pem will allow you to run the python script in Step 3.

If you'd like to generate your own Verification Key for testing purposes, use the following steps. Otherwise, skip to Step 2.

Prior to getting started, you’ll want to make sure you are running Python 3 in order to use the sample code to generate an RSA keypair and signature. You can find this code by expanding the /api/banks/{bank_guid}/verification_keys POST API call in the API Documentation.

Inside the request body, you’ll need to replace the public_key, nonce, and signature fields, where:

  • Public_key = Your generated public RSA key
  • Nonce = The nonce or data you used in the signing process
  • Signature = Your generated signature from the singing process

After you’ve modified the JSON with your specific key and signature inputs, you can click the Execute button to create your verification key. If you entered the correct public key, nonce and signature, your creation request will complete successfully, and you will receive a response similar to the below:

{
  "guid": "your-verification-key-guid",
  "bank_guid": "your-bank-guid",
  "type": "attestation",
  "state": "storing",
  "algorithm": "RS512",
  "fingerprint": "string",
  "created_at": "2022-05-13T13:49:04.956Z"
}

To ensure that your verification key was properly accepted and decoded, head over to the /api/bank_verification_keys/{verification_key_guid} GET call, and click Try it out. Paste in your Verification GUID and click Execute. You’ll see a response similar to:

{
  "guid": "your-verification-guid",
  "bank_guid": "your-bank-guid",
  "type": "attestation",
  "state": "verified",
  "algorithm": "RS512",
  "fingerprint": "3CCu/SXkmXnWS7edjizv3P57DnismM8SSTBE8CbJihE=",
  "created_at": "2022-05-10T18:03:16.357Z"
}

We’re looking for the state to be verified. If the state is failed, you’ll have to go back and check your key and signature generation process for correctness.

Now with your verification key successfully created, we can move on to creating a Customer and attaching a verified Identity Record.

2. Creating a Customer

Creating a Customer is fairly straightforward. Simply navigate to the /api/customers POST API call and expand the entry.

Since creation of a customer is about just creating the base entity, there are no input parameters required to create the Customer. Make sure you are still authenticated, then click the Try it Out button, and click execute. If the execution was successful you’ll see the details of the new Customer object you created:

{
  "guid": "your-customer-guid",
  "customer_type": "individual",
  "created_at": "2022-05-13T13:54:16.710Z"
}

To verify the customer exists, you can navigate to the /api/customers GET API call, and click Execute to have all customers attached to your Bank returned. The response will be similar to this:

{
  "total": 0,
  "page": 0,
  "per_page": 0,
  "objects": [
    {
      "guid": "your-customer-guid",
      "customer_type": "individual",
      "created_at": "2022-05-13T13:55:08.460Z"
    }
  ]
}

With the customer created, we can now move on to creating and attaching an Identity Record.

3. Creating an Identity Record for your Customer

An Identity Record is a KYC (Know Your Customer) requirement for users to be able to execute any transactions on the Cybrid platform. The record consists of an Attestation that your organization has faithfully completed KYC on the Customer in question.

To proceed, you’ll need Python 3 installed on your computer, and then head over to the /api/identity_records POST API call to find sample Python code to generate your Attestation.

Note that there are several libraries that this sample code leverages. Most are installed natively as part of Python 3, but you may have to manually install some, such as the jwcrypto library.

This sample code will load your saved verification_key.pem file from step 1 in order to generate a new signing key. There’s a few other pieces of information that you’ll need to fill out in this sample code:

  • Verification_key_guid: this will be the GUID generated from the verification key creation in step 2
  • Bank_guid: this is the GUID from the bank you generated in the Getting Started article
  • Customer_guid: this will be the GUID from the customer you created in Step 2

Once you’ve filled in all of the appropriate GUIDs, go ahead and run the script to generate and output your signed JWT token. You’ll use this token as the record of attestation and to create the Identity Record for your customer.

To proceed, head over to the /api/identity_records POST API call, expand it, and click Try it out.  You’ll then need to fill in the following JSON request body:

{
  "customer_guid": "your-customer-guid",
  "type": "attestation",
  "attestation_details": {
    "token": "string"
  }
}

You’ll need to paste in the GUID of the Customer you’d like to create the identity record for, and the generated token from the Python identity script. Once entered, click the Execute button, and you should see a response similar to this:

{
  "guid": "your_identity_record_guid",
  "customer_guid": "your_customer_guid",
  "type": "attestation",
  "attestation_details": {
    "state": "storing"
  },
  "created_at": "2022-05-13T14:06:29.281Z"
}

Copy the returned Identity Record GUID, as we’ll want to query it immediately to confirm that the platform verified your JWT token. To do this, expand the /api/identity_records GET call, click Try it out, paste in your Identity Record GUID, and click Execute. The response should look like the below.

{
  "guid": "your_identity_record_guid",
  "customer_guid": "your_customer_guid",
  "type": "attestation",
  "attestation_details": {
    "state": "verified"
  },
  "created_at": "2022-05-11T17:18:30.407Z"
}

If the state is not verified, then something went wrong with verifying the record. Check your inputs in the identity script and try again. The platform will always take the most recent Identity Record for a Customer, so don’t worry if you have to recreate this record.

Now with this identity record in place, you can move on to account creation.

4. Create an Account for the Customer

For each cryptocurrency a Customer trades in, they will need an account. For example, to execute trades for both Bitcoin (BTC) and Ethereum (ETH), you’ll need to create a BTC account and an ETH account for the Customer.

Head on over to the /api/accounts POST call, expand it, and click Try it out. You’ll see a JSON request body that we need to fill in with the Customer GUID, the Asset type, and a friendly Name for the account.

If you want to see a list of which assets are supported, execute the /api/assets GET call.

Go ahead and enter your Customer GUID, enter an Asset, such as BTC, and give the account a name. If successful, you should receive a 201 response, with the new account details, similar to below:

{
  "type": "trading",
  "guid": "your_account_guid",
  "created_at": "2022-05-11T16:55:55.775Z",
  "asset": "BTC",
  "name": "Bitcoin Account",
  "bank_guid": "your_bank_guid",
  "customer_guid": "your_customer_guid",
  "platform_balance": 0,
  "platform_available": 0,
  "state": "current_state"
}

Note that accounts have a state property, that will be storing after the account creation call, and created once the account is fully provisioned. In the sandbox environment provisioning is instantaneous, however in the production environment there are additional provisioning steps which may add a short delay between the storing and created states. When planning production integrations, be sure to engineer for these two possible states.

With a BTC Account now created, and attached to the customer, we are prepared to generate a quote and execute a trade.

5. Generate a Quote

To generate a Quote, we’ll use the /api/quotes POST API call. Navigate to the call in the documentation, expand it, and click Try it out.

You’ll need to have your Customer GUID handy. If you didn’t copy it earlier, you can head over to the /api/customers GET call and execute it to return a list of customers you’ve created. Copy the customer GUID and head back to /api/quotes.

You’ll also need to specify a symbol. You can see a full list of supported symbols by executing the /api/symbols GET call. The symbols are always in pair format, for example BTC-USD.

Quotes in the sandbox environment are valid for 30 seconds. This is a convenience feature for testing, as production environment quotes are only valid for 8 seconds. As such, you may want to follow through the instructions below to get a feel for generating a quote, then take a look at Step 6 for executing a trade. When you feel comfortable with that step, come back here to generate another quote and immediately use your Quote ID to execute the Trade.

In the request body, paste your Customer Guid into the customer_guid placeholder string. Update the symbol to your desired cryptocurrency, such as BTC-USD, and set the receive_amount to the amount of BTC you’d like to receive, such as 10,000,000. When you are entering the receive amount, be aware that the number is always in the base unit of the currency. For example, the base unit of Bitcoin is 1 Satoshi, and there are 100,000,000 satoshis in a single Bitcoin. So if you want to purchase 0.1 of a bitcoin, that equates to 10,000,000 satoshis, hence the number we suggested for the receive_amount.

Note that there are two ways to prepare a quote. The first is to enter the receive amount, which specifies the amount of cryptocurrency to provide a fiat quote for. The second is to enter the deliver amount, which specifies the amount of fiat a customer would like to spend, and will determine the resultant amount of crypto they will receive. The request body only accepts one of either receive_amount or deliver_amount, so make sure to include only one. In our case, delete the deliver_amount key.

Go ahead and click Execute to generate a Quote. You’ll see something similar to this:

{
  "guid": "your_quote_guid",
  "customer_guid": "your_customer_guid",
  "symbol": "BTC-USD",
  "side": "buy",
  "receive_amount": 10000000,
  "deliver_amount": 293407,
  "fee": 0,
  "issued_at": "2022-05-11T19:47:52.048Z",
  "expires_at": "2022-05-11T19:48:22.048Z"
}

Reminder: The quote is only valid for 30 seconds. If you try to execute a trade after 30 seconds the trade will error out.

6. Execute your Trade

Now that we know how to generate a quote, we can proceed to execute a trade. Navigate to the /api/trades POST API, expand it, and click Try it out. You’ll see there’s only one input to the request body JSON, and that’s the Quote ID. The Trade process is simply executing the details from the Quote ID you provide.

In the JSON request body, enter the Quote ID from the previous step, ensuring that you generated the quote less than 30 seconds ago. If the quote is still valid, you’ll see something similar to this:

{
  "guid": "your_trade_guid",
  "customer_guid": "your_customer_guid",
  "quote_guid": "your_quote_guid",
  "symbol": "BTC-USD",
  "side": "buy",
  "state": "storing",
  "receive_amount": 10000000,
  "deliver_amount": 293063,
  "fee": 0,
  "created_at": "2022-05-11T19:56:42.856Z"
}

Note that the state is initially storing. To check if the trade completed successfully, expand the /api/trades/{trade_guid} GET API, and enter the Trade GUID from the executed trade. Assuming all is well, you should see something similar to this:

{
  "guid": "your_trade_guid",
  "customer_guid": "your_customer_guid",
  "quote_guid": "your_quote_guid",
  "symbol": "BTC-USD",
  "side": "buy",
  "state": "completed",
  "receive_amount": 10000000,
  "deliver_amount": 293063,
  "fee": 0,
  "created_at": "2022-05-11T19:56:42.856Z"
}

The trade state is now completed. There’s a few other states that the trade can be in, including:

  • Storing - Trade details are being stored in the platform
  • Initiating - Trade execution has begun
  • Pending - Platform is waiting for the trade to complete
  • Completed - Trade has successfully completed
  • Failed - Platform was not able to successfully complete the trade

To verify your trade completed successfully, head over to the /api/accounts GET call, expand it, click Try it out, and Execute. Look for the Account associated with your Customer. You should see something similar to this:

{
      "type": "trading",
      "guid": "your_acconut_guid",
      "created_at": "2022-05-11T16:55:55.775Z",
      "asset": "BTC",
      "name": "Bitcoin Account",
      "customer_guid": "your_customer_guid",
      "platform_balance": 10000000,
      "platform_available": 0
    }

The platform_balance indicates a balance of 10,000,000! Congrats, you’ve successfully executed a trade for your customer in the simulated sandbox environment.

Wrap Up

Let’s recap what we did:

  1. We created a Verification Key that will subsequently be used to sign all of your Identity Record Attestations.
  2. We created a Customer object that will be associated with Identity Records, Accounts, Quotes and Trades.
  3. We created a signed JWT Attestation and created an Identity Record with the Attestation, attached to the Customer, to indicate that you have previously completed KYC for this customer.
  4. We created a BTC Account, in order to be able execute trades in the BTC currency
  5. We created a Quote for the symbol BTC-USD, with the expected receive amount of 10,000,000 Satoshis (or 0.1 BTC).
  6. We executed a Trade with the created Quote ID to successfully receive 0.1 BTC.

With your new Verification Key in hand, you can repeat steps 2-6 to create new Customers, attach Identity Records, generate Quotes and execute Trades.

What’s Next?

Now that you've successfully created a customer and executed trades, you can move on to interacting with that customer via the Cybrid Web Demo App. Simply follow the instructions in Running the Web Demo App guide.

You can also start investigating all of our code in the Cybrid Github repository.

Happy Coding!