Getting Started in the Cybrid Sandbox

This article will discuss how to get started in the Cybrid Sandbox.

The Cybrid Sandbox is an environment where you can get acquainted with our API’s and functionality, while being able to test out simulated activity. The Sandbox is a standalone environment that is not connected to production systems, designed to enable customers to get comfortable with the Cybrid Tech stack and complete integrations in a safe environment.

Two simple concepts will be helpful to understand for this article: Organizations and Banks.

Organizations are meant to represent your entire org, and are the parent object in our data model for all other objects, including Banks.

Banks are owned by an Organization, hold a set of customers and downstream accounts, and are associated with specific Cybrid products. Banks are created in either Sandbox or Production mode, and for the purposes of this article, and Sandbox testing, we’ll be focusing on Sandbox Banks.

To get started in the Sandbox follow the below steps:

1. Sign in to the Sandbox Portal at https://id.demo.cybrid.app/

You can log into the Cybrid Sandbox ID portal using either your Google or Github accounts:

2. Create your Bank and API Keys

Once logged in, you’ll be prompted to complete a couple of steps, including giving your Organization a name, creating a Bank, and generating an API key pair.

Once you’ve created your Organization and Bank name you can click the Generate button to generate an API key pair, consisting of a Client ID and Client Secret.

Your generated ID and Secret will be shown. Simply hover over the Client Secret to reveal it. Copy buttons on the right side of the fields provide a convenient way to copy/paste.

We highly recommend you save the Client Secret in a secure location for future reference, as the Secret will not be shown again once you navigate away from this page.

3. Accessing API Documentation

Once you’ve got your Client ID and Secret safely stored, you can begin to explore the API and read the documentation. After generating your keys, you’ll be provided links to download our OpenAPI 3.0 Schema, or jump over to our online API documentation.

Here are the links for reference:

4. Use the API to Query Your Bank

There’s a couple different ways to get started with our API, but the easiest way is via our interactive online documentation. We’ll describe how to query your Bank info via our docs, as well as via curl if you prefer the command-line interface.

Querying Bank via API Docs

To query your Bank via the docs head over to our documentation. In order to make your first call, you’ll need to first authenticate to the API. Simply click the Authorize button:

You’ll be prompted to authorize with either your Client ID and Secret, or a Bearer Token. For now, we’ll use your generated ID and Secret, as shown below:

After filling in you ID and Secret, click ‘select all’ to authorize all scopes, then scroll to the bottom of the dialog. Selecting all scopes makes testing easier, but you can look at each individual API call, where the required scope will be listed in the description, and limit your authorization to just the scopes you’re interested in testing.

A successful authorization will look like this:

You can now safely close the Authorization dialog and scroll down to the Bank API set:

You’re going to use the /api/banks/{bank_guid} GET API. You’ll need to copy your Bank GUID from the Portal registration screen. Once copied, click the ‘Try it out’ button, and paste your Bank GUID in. Once paste, simply click the Execute button to query the API.

After the query executes, you’ll receive a JSON query response like this:

Additionally, you’ll be provided with a pre-filled curl query to test out this API call in your terminal window. Running the curl command will return the same JSON response as above.

curl -X 'GET' \
  'https://bank.demo.cybrid.app/api/your-bank-guid' \
  -H 'accept: application/json' \
  -H 'Authorization: bearer eyJraWQioiJsWTPaTI2sX' 

5. Setting Your Trade Configurations

The last step in setting up your Bank is to set a Trade Configuration, which determines the fee structure that the Cybrid platform will apply to all trades initiated by your organization.

Setting a Trade Configuration will determine how you would like to generate revenue, and there’s two models which Cybrid supports; a fixed fee per transaction and a percentage spread per transaction. You can set one, or the other, or both configurations, depending on how you would like to structure fees for your end customers.

To set the Trade Configuration, head over to the /api/trading_configurations POST API call in the API docs. Make sure you’re still authenticated, then click Try it out. You’ll see a sample request body like the following:

{
  "asset": "string",
  "fees": [
    {
      "type": "spread",
      "spread_fee": 0,
      "fixed_fee": 0
    }
  ]
}

While the sample JSON does include values for both spread and fee, the API will only accept one type at a time. Additionally, the fee is set per fiat asset. In this example we’ll focus on USD, so let’s update the asset string to be “USD”.

Now let's set a percentage spread by setting a value for spread_fee, such as 50, which equates to 50 basis points, or 0.5% (half a percent). Finally, delete the fixed_fee line and click Execute. If the call completed successfully, you’ll see a JSON response similar to the following: 

{
  "guid": "your-trade-config-guid",
  "bank_guid": "your-bank-guid",
  "asset": "USD",
  "created_at": "2022-05-16T20:12:13.408Z",
  "fees": [
    {
      "type": "spread",
      "spread_fee": 50
    }
  ]
}

At any time you can use the /api/trade_configurations GET API call to retrieve all of the configurations you’ve got in the system.

Congratulations, you've made it through bank setup!

What’s Next?

Now that you're successfully querying your Bank with your generated Client ID and Secret, and have set a Trade Configuration, you can move on to creating customers, identity records, accounts and executing simulated trades! Check out our next article in this series: Getting Ready for Trading.

You can also start investigating our SDKs at the Cybrid Github repository.

Happy Coding!