Overview

Embedded Brokerage (Closed Loop)

This guide will walk you through using these APIs to deploy an embedded digital asset trading solution.

This walkthrough makes three assumptions:



  1. User trades will be funded by the bank or fintech, i.e. users will not be maintaining individual fiat balances with Fuze. Instead, the bank or fintech settles with Fuze, who in turn will settle with its users separately. This configuration will be done by us - there’s no change to be done by you.
  2. Fuze will onboard customers via a KYC reliance model - where Fuze can rely on the KYC data collected and verified by the regulated partner at the time of onboarding with the partner.
  3. There is no deposit or withdrawal of crypto allowed - i.e. it is a closed-loop implementation. While the APIs from Fuze are some whether it's closed-loop or open-loop, functionality related to virtual asset deposits and withdrawals have not been covered here.

Other variations of the above assumptions are possible. Feel free to reach out to us.

User Onboarding

Based on the jurisdiction, Fuze requires varying levels of User KYC data in order to create an account. This entire process can be performed via APIs.

User Consent

As a partner, you will have to ensure that the User is shown T&Cs, that include consent to transfer KYC data to Fuze. The User must agree to this on your app or website, before any data is transferred to Fuze via APIs.

Create User on Fuze

Once consent has been taken, you can now create a User on Fuze using this API. Every request will consist the following sets data:

orgUserId: All transactions on Fuze are associated with an orgUserId. This can be any string that uniquely identifies your Users within your systems. Ideally this is a UUID, with no PII. A ledger for every orgUserId is maintained by Fuze, and the balances can be queried at any point.

kyc and tnc: true indicate that you have verified the User’s KYC information, and that the User has agreed to T&Cs (consent to transfer data to Fuze).

kycData: This will be all the KYC data fields of a User. Keep in mind that the list given in the example below is exhaustive. Actual KYC data differs from case to case, and will be based on mutual agreement with Compliance Teams.

In case any of the required fields are absent, Fuze will respond indicating exactly which fields are missing. As mentioned above, whether a given field is mandatory or not will change based on the jurisdiction, and mutual agreement with the compliance teams.

If all the required fields are present, Fuze will respond showing that the User has been created, and that the User is in PENDING state. PENDING indicates that there KYC documents that Fuze should be sent, which we will cover next.

KYC Document Upload

You can now transfer the documents to Fuze using this API. Usually, this would mean a copy of the National ID or a Passport. Other documents can include liveliness check proofs and more. The exact documents required will be configured based on agreement between compliance teams.

To upload a document, you will need to generate an upload link. This is presigned link to object storage to which you can upload your file.

A valid response will contain a url to which you can upload the file.

EDD Documents

In case a particular customer is categorized as high risk, we expect additional documents to be uploaded and EDD conducted. The process is similar to the above, with the only difference being the docCategory and docSubCategory fields.

For example if there are two documents for EDD - a screening result and adverse media search result - then you would need to call the get-upload-link API twice, once for each document.

The actual EDD docs to be transferred will be agreed upon between respective compliance teams. The above docs mentioned are examples.

Once both documents have been uploaded, you will have to inform Fuze that the EDD process is complete. This can be done by calling this API

User Active Callback

Once all files are uploaded, you will receive a webhook indicating that the status of the User has changed to ACTIVE. The webhook will look as follows:

{
  "event": {
    "orgId": 10,
    "entity": "Users",
    "numRetries": 0,
    "updatedAt": "2023-12-14T12:35:02.894Z",
    "createdAt": "2023-12-14T12:35:02.894Z"
  },
  "data": {
    "orgUserId": "barbara_allen",
    "orgId": 10,
    "kyc": true,
    "tnc": true,
    "userStatus": "ACTIVE",
    "userType": "CONSUMER"
  }
}

Separately, you can also query the getUser API, which will give you the current status of the User.

In case the User is in PENDING state, the response will also list the documents that are yet to be transferred to Fuze.

Asset Data

Fuze provides a range of asset data that can be combined in different ways, in various sections of the overall user journey.

Spot Price

You can fetch the live price of the asset using this API endpoint.

A typical response will look like this:

{
    "code": 200,
    "data": {
        "timestamp": 1746181915265,
        "value": 356247.8757763
    },
    "error": null
}

Live candle price (buy and sell price)

Fuze also passes live buy and sell prices - which can be used in the buy/sell flow to give users estimates of what they can expect when they place their orders. This API also returns the price with markups (if any, and mutually agreed between Fuze and the partner) The prices can be fetches using this API: https://dev.fuze.finance/reference/openloopgetcandleprice

Historical Prices

In case you want to construct charts in your UX, you can fetch Fuze's historical price data using this API endpoint.

Asset Metadata

You can get metadata on assets, which you can use to enrich the embedded app experience. This includes asset icon files, descriptions, market cap etc. You can see the API here.

A sample response looks as follows:

{
  "code": 200,
  "data": {
    "asset": "BTC",
    "chainsAndNetworks": [
      {
        "chain": "BITCOIN",
        "network": "MAINNET"
      }
    ],
    "policies": {
      "NAME": "BTC",
      "ICON": "https://fuze.finance/symbol/btc.jpg",
      "ASSET_ENABLE": false,
      "LOCAL_CURRENCY": "AED",
      "MARKET_CAP": 100000,
      "CURRENT_PRICE": 1000,
      "HIGH_24HR": 1000,
      "LOW_24HR": 1000,
      "PRICE_CHANGE_PERCENT_24H": 10.1
    }
  },
  "error": null
}

As you can see, the same API is also used to tell whether an asset is enabled or not. So as long as your app is consuming this API, you can always enable new tokens (Asset_Enable will be True) seamlessly and quickly, without requiring an app release.

Other data - like minimum and maximum trade values for individual tokens, and volatility indicators, are also returned in this API call. This information can be used to further enhance the buying and selling experience.

Prefunding

Prefunding essentially means that as a partner, you will deposit fiat with Fuze. These funds will be used to fulfil trades by your consumers. This means that Fuze has no visibility into how you get funds from the consumers, and how you settle with them. Keep in mind that this only pertains to fiat. All crypto balances will be maintained by Fuze at a consumer level.

To prefund Fuze, you will need to create an Internal User. You can do so by hitting this API:

The internal user is just a user type that is associated with you, and not any end-user.

Buy Orders

In case of a buy order, you need to ensure that sufficient funds are available in the consumer account to fulfil the transaction. You can choose to transfer the exact amount right before the order, by using the Internal Transfer API.

Once the trade is done, any balance, if any, can be transferred back to your internal user account.

Sell Orders

In case of a sell order, the sale amount will be credited to the consumer's account once the transaction is done. You can then hit the internal transfer API again and move the funds back to your internal account.

📘

This prefunding model is the most common and standard funding model. There are other funding models possible and currently implemented, which can be mutually agreed upon with Fuze. For the sake of simplicity, other models are not covered in this walkthrough.

Placing Orders

Once you've ensured that the user has sufficient balance, you can go ahead and place an order.

Order API

Click here for the API Reference

You can now place orders against the orgUserId.

To place an order, you will need to pass the orgUserId, along with the symbol, quantity and the operation.

orgUserId: The user.
symbol: The currency pair you want to trade. quantity: The amount of tokens (digital asset) to buy or sell. quoteQuantity: The amount of base currency (USD/AED) to buy or sell. operation: BUY or SELL clientOrderId: Optional idempotency key which ensures the same order is not placed twice.

So if you want to buy 0.01 BTC for barbara_allen_2, you pass the request below:


{
    "orgUserId": "barbara_allen_2",
    "symbol": "BTC_USD",
    "operation": "BUY",
    "quantity": 0.01,
    "quoteQuantity": 0.01,
    "clientOrderId": '5468bbb7-5e5f-425c-a6eb-b89e19a0298a',
}

Or you could send an order of quoteQuantity.

{
    "orgUserId": "barbara_allen_2",
    "symbol": "BTC_USD",
    "operation": "BUY",
    "quoteQuantity": 100,
    "clientOrderId": '5468bbb7-5e5f-425c-a6eb-b89e19a0298a',
}

A successful response will contain an id which can be used to query the status of the order later.

{
    "code": 200,
    "data": {
        "id": 107,
        "orgId": 28,
        "orgUserId": "barbara_allen_2",
        "symbol": "BTC_USD",
        "side": "BUY",
        "quantity": 0.01,
        "rejectionReason": null,
        "filled": 0
    },
    "error": null
}

Check Order Status

Orders are almost always instant. Nonetheless, you can set up a web hook that will notify you whether the transaction was successful. We’ve covered more details about our webhooks here .

To check the status of the order, using REST and this API endpoint

{
    "code": 200,
    "data": {
        "id": 107,
        "clientOrderId": "5468bbb7-5e5f-425c-a6eb-b89e19a0298a",
        "orgId": 28,
        "orgUserId": "barbara_allen_2",
        "symbol": "BTC_USD",
        "price": 0,
        "averagePrice": 26749.08,
        "side": "BUY",
        "quantity": 0.01,
        "filled": 0.01,
        "status": "COMPLETED",
        "rejectionReason": null,
        "createdAt": "2023-06-08T07:53:11.688Z",
        "updatedAt": "2023-06-08T07:53:12.658Z"
    },
    "error": null
}

View Order History

You can now fetch the order history of a user by passing the orgUserId on this endpoint

In the response, you will get a list of all transactions made by a user. You can use this data to create a transaction history view for your users.

{
    "code": 200,
    "data": [
        {
            "id": 105,
            "orgId": 28,
            "orgUserId": "barbara_allen_2",
            "symbol": "ETH_USD",
            "price": 0,
            "averagePrice": 0,
            "side": "BUY",
            "quantity": 0.01,
            "filled": 0,
            "status": "REJECTED",
            "rejectionReason": "ETH is disabled for trading",
            "createdAt": "2023-06-08T07:51:32.051Z",
            "updatedAt": "2023-06-08T07:51:32.447Z"
        },
        {
            "id": 107,
            "orgId": 28,
            "orgUserId": "barbara_allen_2",
            "symbol": "BTC_USD",
            "price": 0,
            "averagePrice": 26749.08,
            "side": "BUY",
            "quantity": 0.01,
            "filled": 0.01,
            "status": "COMPLETED",
            "rejectionReason": null,
            "createdAt": "2023-06-08T07:53:11.688Z",
            "updatedAt": "2023-06-08T07:53:12.658Z"
        }
    ],
    "error": null
}

We have more features in the pipeline that further enrich the trading experience. These include PnL data, Watchlists and Price Alerts. We'll keep adding them to the docs as we release them. In case you require any of these, or other features, do let us know.


Other features

Fuze gives you a variety of other features via APIs. These can be put together in unique ways, such that you can offer customers a distinct product experience.

Profit and Loss

You can fetch invested and current values of a user's portfolio, broken down by asset, and/or time intervals. The currency of the PnL will be the base currency used for trades. The API reference is can be found here: https://dev.fuze.finance/reference/openloopgetuserpnl

News

You can fetch news associated with a given set of tokens. This can be used to enrich the token page, or serve as a newsfeed on the homepage. The API is flexible, letting you fetch news for an array of tokens. All news articles have a headline, subheadline and an image, along with the source URL. The API reference can be found here: https://dev.fuze.finance/reference/openloopnewspost

Watchlists

This feature can be used to let your users maintain watchlists for tokens. You can create more than one watchlist per user, each with a different name. The watchlists can be edited as well. The API reference can be found here: https://dev.fuze.finance/reference/openloopfetchwatchlistforuser

Updated 5 days ago