This documentation is designed for our Business Partners, interested in electronically connecting with BSD Broker.

In general, BSD Broker accommodates two forms of service usage for the partners:

• B2B: These partners use trading and other functionalities without individual user management.
• B2B2C: Designed for those who require access on a per-user basis with user management functions.

Three environments are available to facilitate integration at different stages:

• Production - live version for real-world use: https://api-broker.bsdigital.com
• Prelive - for testing with the current release candidate: https://api-prelive-broker.bsdigital.com
• Sandbox - explore the latest development changes in a controlled environment: https://api-sandbox-broker.bsdigital.com

MiCA regulation:

• Sustainability Indicators
• Institutional Broker Quality Report

Specific endpoint errors are descibed under specific endpoints, some errors are common to all requests. When contacting BSD support please always provide value of trace response parameter so we can try to find more info about specific error in application logs

Error response types

Our API can return two types of error responses depending on the nature of the error encountered:

Standard errors

For other types of errors that do not involve validation, the response does not include an errors array. Instead, the response provides a clear message and code that indicate the nature of the error, along with other relevant details.

Example of a standard error response:

{
  "status": 422,
  "title": "Unprocessable Entity",
  "code": "AssetNotAvailable",
  "message": "Required currency/entity not available in this account",
  "detail": null,
  "errors": null,
  "instance": "/api/v1/user/data",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1"
}

Validation errors

When a request fails due to validation errors, the response includes an errors array filled with all the validation issues encountered. This type of response typically occurs when input data does not meet the criteria set by the API's input validation rules.

Example of a validation error response:

{
  "status": 400,
  "title": "Bad Request",
  "code": "ValidationError",
  "message": "Parameters usage incorrect in the call, check the detail field",
  "detail": null,
  "errors": [
    {
      "code": "PredicateValidator",
      "field": "username",
      "message": "Username is required."
    },
    {
      "code": "PredicateValidator",
      "field": "email",
      "message": "Email address is invalid."
    }
  ],
  "instance": "/api/v1/partner/auth",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1"
}

On sandbox and prelive environments, edge cases can be tested by placing 'special' values for certain fields when calling the API.

This process is initiated manually from the back office dashboard, usually triggered by an email or a support ticket.

In the revocation process, the existing order is put into 'Revoked' status. In addition, a new 'storno' order is created with the same amount and reversed side.

In the price improvement process, the revocation process is applied first. Then, an additional new order is created with the same side as the original order but with a better price.

Example - revoke

1. Order (id:123) for BUY of 1 BTC for 50K € is executed with 'Completed' status.
2. Order (id:123) is revoked with 'Revoked' status. Storno order (id:124) for SELL of 1 BTC for 50K € is executed with 'Completed' status.

Example - price improvement

1. Order (id:123) for BUY of 1 BTC for 50K € is executed with 'Completed' status.
2. Order (id:123) is revoked with 'Revoked' status. Storno order (id:124) for SELL of 1 BTC for 50K € is executed with 'Completed' status.
3. Order (id:125) for BUY of 1 BTC for 49K € is executed with 'Completed' status.

Detecting and processing revokes (and price improvements) can be fully automated by the client backend.

Automatic processing of revoked and price improvement orders using REST API

To detect revoked orders partner should implement a process similar to the one bellow.

$lastProcessedId=id-of-last-processed-order-or-null

Every 5 min:

$revokedOrders = 'Get revoked orders'; startingAfter=$lastProcessedId

for $orderId in $revokedOrders:
{
  $stornoOrderId, $priceImprovementOrderId = 'Get an order'; orderId=$orderId
  $stornoOrder = 'Get an order'; orderId=$stornoOrderId
  
  if $priceImprovementOrderId != null:
    $priceImprovementOrder = 'Get an order'; orderId=$priceImprovementOrderId

  {Process everything}

  $lastProcessedId=$orderId
}

Please note, for brevity, the procedure described above does not include pagination, which a real implementation should include.

Automatic processing of revoked and price improvement orders using FIX API

The process is described in FIX section: Order revoke and price improvement process.

Currently supported crypto assets and their essential details.

Asset Code

This is the code that is used by REST API where assetCode is required.

Amount precision

When specifying amount in crypto-currency (for orders, withdrawals and deposits), number of decimals should not exceed this.

Price precision

All quotes and orders returned from endpoints will have price rounded to 10 decimals.

B2B & B2B2C PARTNER ENDPOINTS

The Get user info endpoint is available both for B2B and B2B2C partner users and has not further restrictions in terms of the partner type.

B2B2C ONLY PARTNER ENDPOINTS

The user management features, such as the endpoints for creating users, changing users, importing user KYC data, changing user KYC data, requesting user deletion are designed for the integration of our B2B2C partners. For B2B partners these endpoints of the API are restricted and will return an HTTP 403 (forbidden) response code.

Onboarding process

The diagram bellow illustrates the entire onboarding process for an end user in a B2B2C environment. The usage of BSDigital user API in the on-boarding process is highlighted within a boxed area.

sequenceDiagram
autonumber
    actor Enduser as Enduser
    Enduser->>Partner App: Register for crypto trading
    Partner App->>Partner Backend: Request KYC data sharability
    critical KYC data must be sharable
        Partner Backend->>+Partner Backend: Check KYC data sharability 
    option KYC data outdated / older than 24 hours
        Partner Backend->>+Partner App: KYC data outdated
        Partner App->>+Enduser: Review KYC data screen <br/> (First name, Last name, Address, Legitimation data, AML data,..etc)
        Enduser->>Partner App: Confirm/Update KYC data
        Partner App->>Partner Backend: Confirm up-to-date KYC
    option Validation Date of ID document outdated
        Partner Backend->>+Partner App: ID document validation outdated
        Partner App->>+Enduser: Upload new ID document screen
        Enduser->>Partner App: Upload ID document (e.g. via phonto or PDF or ...)
        Partner App->>Partner Backend: Forward ID document
        Partner Backend->>+Partner Backend: Store ID document
    end

    Partner Backend->>Partner App: Confirm KYC data sharability
    Partner App->>+Enduser: Success screen
    Enduser->>Partner App: Confirm to continue
    Partner App->>+Enduser: KYC data confirmation/update screen
    Enduser->>Partner App: Confirm/Update KYC data (T&Cs, non-Fatca user, etc.)

    Partner App->>+Partner Backend: KYC submit start
    Partner Backend->>+Partner Backend: Check all KYC data availability (T&C confirmation etc.)    
    Partner App->>+Enduser: KYC pending screen (up to X minutes)        

    rect rgba(102, 102, 255, 0.19)
        note right of Partner Backend: User creation (BSDigital User API)
        Partner Backend->>BSDigital Backend: Request Create user
        BSDigital Backend->>Partner Backend: Return created user ID
        Partner Backend->>Partner Backend: Link BS Digital User ID
        Partner Backend->>BSDigital Backend: Import user KYC data
        BSDigital Backend->>Partner Backend: KYC data has been imported<br/> and is being processed
        BSDigital Backend->>BSDigital Backend: Back office checks (AML, etc.)
        Note over BSDigital Backend,Partner Backend: After all checks have passed
        BSDigital Backend->>Partner Backend: Webhook notification (user_updated)    
    end       

    Partner Backend->>Partner App: KYC submit success
    Partner App->>Enduser: KYC success screen

The highlighted section is divided into three parts:

1. Create a new user at BSDigital

To create a new user you need to call Create a user endpoint. At this point you only need to provide reference data. The response will contain the newly created User-ID, which you need to store in your backend and is needed for all further API calls related to that User. If there is a network error during this call, the call can be repeated. If you wish to change some user data user the Change user endpoint.

2. Import KYC-data for that user

After user is successfully created, you have to import his KYC-data. To do so, you need to call Import user kyc data endpoint and provide user personal information, address and legitimization details as well as tax and AML relevant information. A successful response from this endpoint only means that provided KYC-data was accepted for processing. Trading is not possible yet, until the KYC-data has been processed successfully. You will receive a webhook notification when this happens. If you wish to change the imported kyc data use the Change user kyc data endpoint.

3. Consume webhook-notification

After the KYC has been successfully processed by the BSDigital back-office, a webhook-notification will be sent to your configured webhook-URL. This notification will contain the new KYC-Status of the user:

• if the KYC-Status has been set to 'Confirmed', the user is now able to trade crypto,
• if the KYC-Status has been set to 'Invalid', there is a problem with the KYC-data and you will need to contact us to resolve it.

We offer request for quote orders and market orders.

Request for quote (RFQ) orders

Issuing a request for quote order involves two steps:

1. Calling 'Request a quote' with amount to buy/or sell. A quote with an offered price is returned.
2. Calling 'Place an order', referencing the issued quote. Be aware that the quote is only valid for a limited amount of time (validUntil).

sequenceDiagram
autonumber
    Partner Backend->>BSDigital Backend: Request a quote
    BSDigital Backend->>Partner Backend: Return quote id and price
        
    Partner Backend->>BSDigital Backend: Place an order (quote id)
    BSDigital Backend->>Partner Backend: Return order Id

Some implementation details:

• Specify either fiat-amount or amount. Max order value in EUR is as configured per partner's account. Max amount is limited by users portfolio. If the user requests 10 BTC for sell, but owns only 5 BTC the user will get back quote for 5 BTC.
• A quote is valid for 15 seconds.
• Both order amount and fiat-amount returned by 'Request a quote' must be submitted to 'Place on order'.
• Quote id is same as order id, which means quote id can be used to check if an order was placed in case of network issues.

Market orders

Market orders always execute with current market price. The exact price of the trade is only known after the trade is done.

Issuing a market order involves only a single call to 'Place an order' endpoint.

sequenceDiagram
autonumber
    Partner Backend->>BSDigital Backend: Place an order (orderType=Market)
    BSDigital Backend->>Partner Backend: Return order Id

Some implementation details:

• Specify order type: 'Market'
• Specify either amount or fiatAmount, not both.
• Use clientOrderId to recover from network issues.

Order statuses

Handling application errors

The list of possible application errors and how to handle them is available at this error list. The following diagram shows how to handle most common ones.

sequenceDiagram
autonumber
    Note over Partner App, Partner Backend: reference to either buy or sell process,<br/> which is the same until this point
    Partner App->>Partner Backend: Place the order for the given quote ID
    Partner Backend->>BSDigital Backend: Place the order <br/> POST /api/v1/partner/{partnerId}/users/{userId}/orders<br/><br/> Both order amount and fiat-amount<br/> returned by request quote must be submitted.
    BSDigital Backend->>BSDigital Backend: Check order validity (See error handling for details)
    BSDigital Backend->>BSDigital Backend: Check if the user has been deleted or blocked in the meantime.
    alt 410 Quote expired
        BSDigital Backend->>Partner Backend: Return error
        Partner Backend->>Partner App: It took longer than 15 secs to<br/> place the order with the given quote ID<br/><br/> Display message that quote has expired. <br/><br/> Offer user to request a new quote<br/> with same quantities as before.<br/><br/> The process must start from the point<br/> of requesting a quote again. 
    else 422 Unstable market
        BSDigital Backend->>Partner Backend: Return error
        Partner Backend->>Partner App: The price offered by the quote<br/> and the current market price<br/> have diverged too much.<br/><br/> Display message that order cannot be executed<br/> because of volatile market.<br/><br/> Offer user to request a new quote<br/> with same quantities as before.<br/><br/> The process must start from the point<br/> of requesting a quote again.
    end

Handling network errors and timeouts

If the network connection fails in the process of placing an order (regardless of buy or sell), the order might still be processed by BSDigital backend. It is best to display a message to the user "Processing of order is taking a bit longer, we will notify you when its done". If the order is an buy order, you also have to "block" euros until you are sure of the order status on BSDigital backend. To check that, you need to periodically call GetOrder using the quote id, until it either returns "not found", or returns the placed order with a status corresponding to the statuses described in the Order statuses section. Depending on the response you either return the blocked Euros to the user or not and restart the entire order process from the "request a quote" point again. The following sequence diagram show a potential flow including the endpoint for getting an order list.

sequenceDiagram
autonumber
    Note over Partner App, Partner Backend: reference to either buy or sell process,<br/> which is the same until this point
    Partner App->>Partner Backend: Place the order for the given quote ID
    Partner Backend->>BSDigital Backend: Place the order <br/> POST /api/v1/partner/{partnerId}/users/{userId}/orders<br/><br/> Both order amount and fiat-amount<br/> returned by request quote must be submitted.
    BSDigital Backend->>BSDigital Backend: Check order validity (See error handling for details)
    BSDigital Backend->>BSDigital Backend: Check if the user has been deleted or blocked in the meantime.
    Note over Partner Backend, BSDigital Backend: network issues at this point of time
    BSDigital Backend-xPartner Backend: Connection issues or timeout
    loop check order existance / api recovery
        Partner Backend->>BSDigital Backend: get a the specific order by quote id<br/>/api/v1/partner/{partnerId}/users/{userId}/orders/{quoteId}<br/><br/> The orderId is the ID of the quote
        alt 200 OK and order status is either 'Submitted', 'Completed' or 'Revoked'
            BSDigital Backend->>Partner Backend: return the requested order
            Partner Backend->>Partner Backend: Order has successfully<br/> been placed<br/>Exit loop.
        else 404 and Error code 'NotFound' or status is "Failed"
            BSDigital Backend->>Partner Backend: Return error
            Partner Backend->>Partner Backend: No order with the<br/> given ID found.<br/>Exit loop.
        else Connection issues or timeout
            BSDigital Backend-xPartner Backend: Connection issues or timeout
            Partner Backend->>Partner Backend: Loop until connection issues persist
        end
        Partner Backend->>Partner Backend: check whether order was returned
    end
    alt Order has successfully been placed
        Partner Backend->>Partner App: Return the order
    else Order has not been placed
        Partner Backend->>Partner App: Order was not created.<br/> Start from the beginning with requesting a quote again<br/> and unblock user money
    end

This section covers endpoints related to crypto transfers (deposits and withdrawals).

Transaction history

In order to get a full transaction history, you can obtain that by calling the following endpoints:

• get a (filtered) list of all orders
• get a (filtered) list of all withdrawals
• get a (filtered) list of all deposits