Bitbond Offering Manager API documentation
1.3.4

The Bitbond Offering Manager API provides resource endpoints for fetching projects, creating orders and payments and collecting KYC information about the investors.

The API requires a token based authentication. A bearer token will be provided by Bitbond that will need to be included in the 'Authentication' header for each request to the server, along with an HMAC 'X-Signature' header. The HMAC signature will be used to verify the authenticity of the sender and the integrity of the request in transit.

Authorization

API clients are authorized with bearer tokens. Tokens can be generated in the admin panel as a key/secret pair.
Secret are used to build HMAC-SHA1 signatures on a client side.

Signature generation pseudo code

/**
 * HMAC a hashing function using SHA1 algorythm
 * @param   {String} secret     The secret used to hash the message
 * @param   {String} message    Message to be hashed
 * @return  {Bin}               Binary digest
 */
HMAC = func(secret, message)

/**
 * signatureKey returns derived key
 * @param   {String} secret     The secret from tokens key/secret pair.
 * @param   {String} date       UTC request date in YYYY-MM-DD format
 * @param   {String} method     Request method POST, GET, DELETE etc
 * @param   {String} path       Request path, e.g. /api/v1/access_tokens
 * @return  {Bin}               Derived key used to generate payload signature
 */
signatureKey = func(secret, date, method, path) {
    HMAC(HMAC(HMAC("bitbond" + secret, date), method), path)
}

/**
 * signature returns request signature
 * @param   {String} key        The secret from tokens key/secret pair.
 * @param   {String} payload    Raw request body
 * @return  {String}            Request signature
 */
signature = func(key, payload) {
    HMAC(key, payload).toString()
}

Example in JavaScript

import hmacSHA1 from 'crypto-js/hmac-sha1';

let generateSigningKey = (secret, dateStamp, method, path) => {
  let key = hmacSHA1(dateStamp, `bitbond${secret}`)
  key = hmac(method, key)
  key = hmac(path, key)
  return key
}

let dateStamp = (new Date()).toISOString().substring(0, 10)
let method = request.method
let path = request.url.getPathWithQuery()
let body = request.body && request.body.raw || ''
let signingKey = generateSigningKey(secret, dateStamp, method, path)
let signature = hmacSHA1(body, signingKey).toString()
Headers

To authorize API access this header needs to be added to the request.

Authorization: Bearer [token]
X-Signature: [signature]

Creating orders

To create an order the following necessities need to be met:
  • The current user needs to be approved. A user is approved automatically when they go through a successful video identification session. When a user is approved the approved_at is set to a non-null value and the approved attribute is set to true.
  • An order can only be created for a live project. A live project has its start_date before now and its end_date after.
  • The investment terms need to be accepted by a user for the project they want to invest into. The investment terms are accepted by user for a project by successfully creating terms through the investment_terms endpoint.
  • The order amount must be greater than the project minimum required investment amount.

Creating users
The locale attribute takes en or de as values, with en being set by default when no value is specified.

When an order is created it will have status new and a unique order code will be generated. The order code will be used as a reference code when sending payments.
Once a new payment is created, the details of the payment are analysed and the order status changes accordingly to paid, if the amount sent matches the order, underpaid, if the amount sent is lower than the order and overpaid if the amount sent is larger than the order.
An order can also have status cancelled, either by admin action or by user action. When an order distribution on the blockchain is initiated the order status changes to settled.

Creating identities

An identity contains personal data about a user. Identities are of many types ranging from individuals, legal representatives, and business owners. They share common attributes described in the Identity model. Generally an individual investor will have one identity that collects information regarding contact details, citizenship and taxes. A business investor will hold one legal representative, that will need to be kyc-ed via video identification, and multiple business owners.

VIDEO IDENTIFICATION FLOW

The video identification process is handled through IDnow, as the video identification provider.

There are a few requirements to be able to start a video identification process:

  • an identity needs to be created with contact data and financial information POST /users/{user_id}/identities
  • an address needs to be added for the identity POST /users/{user_id}/identities/{identity_id}/addresses
  • the bank account details need to be filled in for the user POST /users/{user_id}/bank_accounts
  • the identity terms need to be create for the identity POST /users/{user_id}/identities/{identity_id}/identity_terms

If a video identification session is attempted without the above requirements to be met, an error will be thrown.

There are two steps to perform a video identification session:

  • Initiate the session by making a POST request to the /kyc/identities/{identity_id}/video_identifications endpoint
  • Make a GET request to the /kyc/identities/{identity_id}/video_identifications/{id} endpoint to verify the video_identifications object has the idnow_id and the redirect_url attributes filled in. A polling mechanism might be needed to fetch the latest data.

When the redirect_url attribute is present, the user can be redirected to their video provider (IDnow) session.
Once the user goes through the video identification session, a webhook is triggered to synchronize data from the video provider (IDnow) to Bitbond. In order to check the status of the video session make a GET request to the /kyc/identities/{identity_id}/video_identifications/{id} endpoints to verify the object has the status attribute filled in.

The video_identifications object can be accessed through the /identities/{id} endpoint as well.

IMPORTANT NOTE:
On staging, the video identification provider (IDnow) does not automatically trigger the webhook to synchronize data on Bitbond's side, therefore the video_identification object status attribute will never be updated.

At the moment, upon going through the video identification session, the user is not redirected back into the investor application. This feature is work in progress.

Webhooks

Webhook URLs can be added through Admin frontend application. API will automatically retry a webhook if the response status code will be anything other than 200. Webhooks are called with payload in POST request body when the following events happen:

  • distribution_created
    • Is triggered when distribution to Blockchain was processed.
  • kyc_approved
    • Is triggered after successfull auto-approval process when investor finishes the KYC process.
  • kyc_rejected
    • Is triggered when admin user rejects the investor in Asset Manager
  • kyc_video_identification_success
    • Is triggered after the investor goes through a successful IDNOW KYC process.
    • Is tiggered when KYC process is mocked using Asset Manager Labs section (does not apply to production)
  • order_created
    • Is triggered when the endpoint POST /users/:user_id/projects/:project_id/orders is used and after a new order is successfully created.
  • order_status_changed
    • Is triggered when status of an order is updated manually
    • Is triggered when payment is created and order status is changed
  • project_prepared_for_distribution
    • Is triggered when project has done a preparation for distribution cycle.
  • transaction_created (WIP)
Webhook payloads
  • distribution_created
{
  event: 'distribution_created',
  order_id: {String} UUID,
  user_id: {String} UUID,
  project_id: {String} UUID,
}
  • kyc_approved
{
  event: 'kyc_approved',
  user_id: {String} UUID
}
  • kyc_rejected
{
  event: 'kyc_rejected',
  user_id: {String} UUID
}
  • kyc_video_identification_success
{
  event: 'kyc_video_identification_success',
  user_id: {String} UUID
}
  • order_created
{
  event: 'order_created',
  order_id: {String} UUID,
  user_id: {String} UUID,
  project_id: {String} UUID,
}
  • order_status_changed
{
  event: 'order_status_changed',
  order_id: {String} UUID,
  user_id: {String} UUID,
  project_id: {String} UUID,
  status: {String},
}
  • project_prepared_for_distribution
{
  event: 'project_prepared_for_distribution',
  project_id: {String} UUID,
  code: {String},
  percentage: {Number}
}
  • transaction_created (WIP)
{
  event: 'transaction_created',
  transaction_id: {String} UUID,
  custody_account_holder_id: {String} UUID,
  custody_account_id: {String} UUID,
  user_id: {String} UUID
}

This is the documentation for version 1.3.4 of the API. Last update on Jan 23, 2023.

Base URL
https://client-subdomain.bitbond.net/api/v1

Fetch the address of a personal investor

GET /users/{user_id}/kyc/identities/{identity_id}/addresses

Fetch the address of a personal investor, a legal representative or a business owner entity

Path parameters

Responses

GET /users/{user_id}/kyc/identities/{identity_id}/addresses
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/identities/{identity_id}/addresses
Response example (200)
{
  "id": "string",
  "street_additional": "string",
  "city": "string",
  "country": "string",
  "state": "string",
  "street": "string",
  "number": "string",
  "zipcode": "string"
}

Create an address for a personal investor

POST /users/{user_id}/kyc/identities/{identity_id}/addresses

Create an address for a personal investor, legal representative or a business owner entity

Path parameters

Body Required

Address information

Responses

POST /users/{user_id}/kyc/identities/{identity_id}/addresses
curl \
 -X POST https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/identities/{identity_id}/addresses \
 -H "Content-Type: application/json" \
 -d '{"address":{"city":"string","country":"string","state":"string","street":"string","number":"string","zipcode":"string","street_additional":"string"}}'
Request example
{
  "address": {
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string",
    "street_additional": "string"
  }
}
Response example (201)
{
  "id": "string",
  "street_additional": "string",
  "city": "string",
  "country": "string",
  "state": "string",
  "street": "string",
  "number": "string",
  "zipcode": "string"
}

Update the address for a personal investor

PATCH /users/{user_id}/kyc/identities/{identity_id}/addresses/{id}

Update the address for a personal investor, legal representative or business owner entity

Path parameters

Body Required

Address information

Responses

PATCH /users/{user_id}/kyc/identities/{identity_id}/addresses/{id}
curl \
 -X PATCH https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/identities/{identity_id}/addresses/{id} \
 -H "Content-Type: application/json" \
 -d '{"address":{"city":"string","country":"string","state":"string","street":"string","number":"string","zipcode":"string","street_additional":"string"}}'
Request example
{
  "address": {
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string",
    "street_additional": "string"
  }
}
Response example (201)
{
  "id": "string",
  "street_additional": "string",
  "city": "string",
  "country": "string",
  "state": "string",
  "street": "string",
  "number": "string",
  "zipcode": "string"
}

Fetch the address of the business

GET /users/{user_id}/kyc/businesses/{business_id}/addresses

Fetch the address of the business.

Path parameters

Responses

GET /users/{user_id}/kyc/businesses/{business_id}/addresses
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/businesses/{business_id}/addresses
Response example (200)
{
  "id": "string",
  "street_additional": "string",
  "city": "string",
  "country": "string",
  "state": "string",
  "street": "string",
  "number": "string",
  "zipcode": "string"
}

Create an address entry for the business

POST /users/{user_id}/kyc/businesses/{business_id}/addresses

Create an address entry for the business.

Path parameters

Body Required

Address information

Responses

POST /users/{user_id}/kyc/businesses/{business_id}/addresses
curl \
 -X POST https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/businesses/{business_id}/addresses \
 -H "Content-Type: application/json" \
 -d '{"address":{"city":"string","country":"string","state":"string","street":"string","number":"string","zipcode":"string","street_additional":"string"}}'
Request example
{
  "address": {
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string",
    "street_additional": "string"
  }
}
Response example (201)
{
  "id": "string",
  "street_additional": "string",
  "city": "string",
  "country": "string",
  "state": "string",
  "street": "string",
  "number": "string",
  "zipcode": "string"
}

Update the address for the business

PATCH /users/{user_id}/kyc/businesses/{business_id}/addresses/{id}

Update the address for the business.

Path parameters

Body Required

Address information

Responses

PATCH /users/{user_id}/kyc/businesses/{business_id}/addresses/{id}
curl \
 -X PATCH https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/businesses/{business_id}/addresses/{id} \
 -H "Content-Type: application/json" \
 -d '{"address":{"city":"string","country":"string","state":"string","street":"string","number":"string","zipcode":"string","street_additional":"string"}}'
Request example
{
  "address": {
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string",
    "street_additional": "string"
  }
}
Response example (201)
{
  "id": "string",
  "street_additional": "string",
  "city": "string",
  "country": "string",
  "state": "string",
  "street": "string",
  "number": "string",
  "zipcode": "string"
}

Fetch the bank accounts of the current user

GET /users/{user_id}/bank_accounts

Fetch the bank accounts of the current user.

Path parameters

Responses

GET /users/{user_id}/bank_accounts
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/bank_accounts
Response example (200)
{
  "id": "string",
  "iban": "string",
  "bic": "string",
  "bank_name": "string",
  "account_owner": "string"
}

Create bank account for the current user

POST /users/{user_id}/bank_accounts

Create bank account for the current user.

Path parameters

Body Required

Bank account information

Responses

POST /users/{user_id}/bank_accounts
curl \
 -X POST https://client-subdomain.bitbond.net/api/v1/users/{user_id}/bank_accounts \
 -H "Content-Type: application/json" \
 -d '{"bank_account":{"iban":"string","bic":"string","bank_name":"string","account_owner":"string"}}'
Request example
{
  "bank_account": {
    "iban": "string",
    "bic": "string",
    "bank_name": "string",
    "account_owner": "string"
  }
}
Response example (201)
{
  "id": "string",
  "iban": "string",
  "bic": "string",
  "bank_name": "string",
  "account_owner": "string"
}

Update the bank account for the current user

PATCH /users/{user_id}/bank_accounts/{id}

Update the bank account for the current user

Path parameters

Body Required

Bank account information

Responses

PATCH /users/{user_id}/bank_accounts/{id}
curl \
 -X PATCH https://client-subdomain.bitbond.net/api/v1/users/{user_id}/bank_accounts/{id} \
 -H "Content-Type: application/json" \
 -d '{"bank_account":{"iban":"string","bic":"string","bank_name":"string","account_owner":"string"}}'
Request example
{
  "bank_account": {
    "iban": "string",
    "bic": "string",
    "bank_name": "string",
    "account_owner": "string"
  }
}
Response example (201)
{
  "id": "string",
  "iban": "string",
  "bic": "string",
  "bank_name": "string",
  "account_owner": "string"
}

Fetch the businesses for the current user

GET /users/{user_id}/kyc/businesses

Fetch the businesses for the current user.

Path parameters

Responses

GET /users/{user_id}/kyc/businesses
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/businesses
Response example (200)
[
  {
    "id": "string",
    "name": "string",
    "legal_name": "string",
    "tax_id_number": "string",
    "legal_form": "string",
    "register_number": "string",
    "country_of_taxation": "string",
    "second_country_of_taxation": "string",
    "second_tax_id_number": "string",
    "exclusively_taxable_in_country_of_taxation": true
  }
]

Create a business entry for the current user

POST /users/{user_id}/kyc/businesses

Create a business entry for the current user. 'second_country_of_taxation' and 'second_tax_id_number' attributes are required only when exclusively_taxable_in_country_of_taxation is set to false

Path parameters

Body Required

Business information

Responses

POST /users/{user_id}/kyc/businesses
curl \
 -X POST https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/businesses \
 -H "Content-Type: application/json" \
 -d '{"legal_name":"string","tax_id_number":"string","legal_form":"string","register_number":"string","country_of_taxation":"string","second_country_of_taxation":"string","second_tax_id_number":"string","exclusively_taxable_in_country_of_taxation":true}'
Request example
{
  "legal_name": "string",
  "tax_id_number": "string",
  "legal_form": "string",
  "register_number": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "exclusively_taxable_in_country_of_taxation": true
}
Response example (201)
{
  "id": "string",
  "name": "string",
  "legal_name": "string",
  "tax_id_number": "string",
  "legal_form": "string",
  "register_number": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "exclusively_taxable_in_country_of_taxation": true
}

Update the business information

PATCH /users/{user_id}/kyc/businesses/{id}

Update the business information.

Path parameters

Body Required

Business information

Responses

PATCH /users/{user_id}/kyc/businesses/{id}
curl \
 -X PATCH https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/businesses/{id} \
 -H "Content-Type: application/json" \
 -d '{"legal_name":"string","tax_id_number":"string","legal_form":"string","register_number":"string","country_of_taxation":"string","second_country_of_taxation":"string","second_tax_id_number":"string","exclusively_taxable_in_country_of_taxation":true}'
Request example
{
  "legal_name": "string",
  "tax_id_number": "string",
  "legal_form": "string",
  "register_number": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "exclusively_taxable_in_country_of_taxation": true
}
Response example (201)
{
  "id": "string",
  "name": "string",
  "legal_name": "string",
  "tax_id_number": "string",
  "legal_form": "string",
  "register_number": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "exclusively_taxable_in_country_of_taxation": true
}

Fetch the business owners for the current business user

GET /users/{user_id}/kyc/business_owners

Fetch the business owners for the current business user.

Path parameters

Responses

GET /users/{user_id}/kyc/business_owners
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/business_owners
Response example (200)
[
  {
    "id": "string",
    "user_id": "string",
    "company_role": "string",
    "tax_id_number": "string",
    "first_name": "string",
    "last_name": "string",
    "phone_number": "string",
    "citizenship": "string",
    "country_of_birth": "string",
    "date_of_birth": "string",
    "video_identification_completed_at": "string",
    "place_of_birth": "string",
    "family_status": "string",
    "gender": "string",
    "not_us_income_tax": true,
    "trading_on_behalf_of_self": true,
    "title": "string",
    "name_affix": "string",
    "mifid_status": "skipped",
    "name_at_birth": "string",
    "second_citizenship": "string",
    "country_of_taxation": "string",
    "second_country_of_taxation": "string",
    "second_tax_id_number": "string",
    "share": 42.0,
    "sole_right_of_representation": true,
    "exclusively_taxable_in_country_of_taxation": true,
    "type": "string",
    "video_identification_completed": true,
    "address": {
      "id": "string",
      "street_additional": "string",
      "city": "string",
      "country": "string",
      "state": "string",
      "street": "string",
      "number": "string",
      "zipcode": "string"
    },
    "video_identifications": [
      {
        "id": "string",
        "identity_id": "string",
        "idnow_id": "string",
        "redirect_url": "string",
        "statuses": [
          "string"
        ],
        "data": {},
        "url": "string",
        "has_files": true,
        "completed": true,
        "success": true,
        "rejected": true,
        "pending": true,
        "reason": "string",
        "identificationtime": "string",
        "status": "string"
      }
    ],
    "attachments": [
      {
        "id": "string",
        "file": {},
        "filename": "string",
        "document_type": "string",
        "document_id_number": "string",
        "issued_at": "string",
        "expires_at": "string",
        "issuing_authority": "string",
        "issuing_country": "string",
        "content_type": "string"
      }
    ],
    "term": {
      "custody_wallet_terms_acceptance": true,
      "custody_wallet_privacy_acceptance": true
    }
  }
]

Create a business owner for the current business user

POST /users/{user_id}/kyc/business_owners

Create a business owner for the current business user.

Path parameters

Body Required

Business owner information

Responses

POST /users/{user_id}/kyc/business_owners
curl \
 -X POST https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/business_owners \
 -H "Content-Type: application/json" \
 -d '{"tax_id_number":"string","first_name":"string","last_name":"string","citizenship":"string","date_of_birth":"string","title":"string","name_affix":"string","name_at_birth":"string","second_citizenship":"string","country_of_taxation":"string","share":42.0}'
Request example
{
  "tax_id_number": "string",
  "first_name": "string",
  "last_name": "string",
  "citizenship": "string",
  "date_of_birth": "string",
  "title": "string",
  "name_affix": "string",
  "name_at_birth": "string",
  "second_citizenship": "string",
  "country_of_taxation": "string",
  "share": 42.0
}
Response example (201)
{
  "id": "string",
  "user_id": "string",
  "company_role": "string",
  "tax_id_number": "string",
  "first_name": "string",
  "last_name": "string",
  "phone_number": "string",
  "citizenship": "string",
  "country_of_birth": "string",
  "date_of_birth": "string",
  "video_identification_completed_at": "string",
  "place_of_birth": "string",
  "family_status": "string",
  "gender": "string",
  "not_us_income_tax": true,
  "trading_on_behalf_of_self": true,
  "title": "string",
  "name_affix": "string",
  "mifid_status": "skipped",
  "name_at_birth": "string",
  "second_citizenship": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "share": 42.0,
  "sole_right_of_representation": true,
  "exclusively_taxable_in_country_of_taxation": true,
  "type": "string",
  "video_identification_completed": true,
  "address": {
    "id": "string",
    "street_additional": "string",
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string"
  },
  "video_identifications": [
    {
      "id": "string",
      "identity_id": "string",
      "idnow_id": "string",
      "redirect_url": "string",
      "statuses": [
        "string"
      ],
      "data": {},
      "url": "string",
      "has_files": true,
      "completed": true,
      "success": true,
      "rejected": true,
      "pending": true,
      "reason": "string",
      "identificationtime": "string",
      "status": "string"
    }
  ],
  "attachments": [
    {
      "id": "string",
      "file": {},
      "filename": "string",
      "document_type": "string",
      "document_id_number": "string",
      "issued_at": "string",
      "expires_at": "string",
      "issuing_authority": "string",
      "issuing_country": "string",
      "content_type": "string"
    }
  ],
  "term": {
    "custody_wallet_terms_acceptance": true,
    "custody_wallet_privacy_acceptance": true
  }
}

Fetch the business owner for the current business user based on the id

GET /users/{user_id}/kyc/business_owners/{id}

Fetch the business owner for the current business user based on the id.

Path parameters

Responses

GET /users/{user_id}/kyc/business_owners/{id}
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/business_owners/{id}
Response example (200)
{
  "id": "string",
  "user_id": "string",
  "company_role": "string",
  "tax_id_number": "string",
  "first_name": "string",
  "last_name": "string",
  "phone_number": "string",
  "citizenship": "string",
  "country_of_birth": "string",
  "date_of_birth": "string",
  "video_identification_completed_at": "string",
  "place_of_birth": "string",
  "family_status": "string",
  "gender": "string",
  "not_us_income_tax": true,
  "trading_on_behalf_of_self": true,
  "title": "string",
  "name_affix": "string",
  "mifid_status": "skipped",
  "name_at_birth": "string",
  "second_citizenship": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "share": 42.0,
  "sole_right_of_representation": true,
  "exclusively_taxable_in_country_of_taxation": true,
  "type": "string",
  "video_identification_completed": true,
  "address": {
    "id": "string",
    "street_additional": "string",
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string"
  },
  "video_identifications": [
    {
      "id": "string",
      "identity_id": "string",
      "idnow_id": "string",
      "redirect_url": "string",
      "statuses": [
        "string"
      ],
      "data": {},
      "url": "string",
      "has_files": true,
      "completed": true,
      "success": true,
      "rejected": true,
      "pending": true,
      "reason": "string",
      "identificationtime": "string",
      "status": "string"
    }
  ],
  "attachments": [
    {
      "id": "string",
      "file": {},
      "filename": "string",
      "document_type": "string",
      "document_id_number": "string",
      "issued_at": "string",
      "expires_at": "string",
      "issuing_authority": "string",
      "issuing_country": "string",
      "content_type": "string"
    }
  ],
  "term": {
    "custody_wallet_terms_acceptance": true,
    "custody_wallet_privacy_acceptance": true
  }
}

Delete the business owner for the current business user

DELETE /users/{user_id}/kyc/business_owners/{id}

Delete the business owner for the current business user.

Path parameters

Responses

  • 200

    Request successful

  • 401

    Authorization information is missing or invalid.

  • 422

    Request body has errors or invalid.

DELETE /users/{user_id}/kyc/business_owners/{id}
curl \
 -X DELETE https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/business_owners/{id}

Update the business owner for the current business user

PATCH /users/{user_id}/kyc/business_owners/{id}

Update the business owner for the current business user.

Path parameters

Body Required

Business owner information

Responses

PATCH /users/{user_id}/kyc/business_owners/{id}
curl \
 -X PATCH https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/business_owners/{id} \
 -H "Content-Type: application/json" \
 -d '{"tax_id_number":"string","first_name":"string","last_name":"string","citizenship":"string","date_of_birth":"string","title":"string","name_affix":"string","name_at_birth":"string","second_citizenship":"string","country_of_taxation":"string","share":42.0}'
Request example
{
  "tax_id_number": "string",
  "first_name": "string",
  "last_name": "string",
  "citizenship": "string",
  "date_of_birth": "string",
  "title": "string",
  "name_affix": "string",
  "name_at_birth": "string",
  "second_citizenship": "string",
  "country_of_taxation": "string",
  "share": 42.0
}
Response example (201)
{
  "id": "string",
  "user_id": "string",
  "company_role": "string",
  "tax_id_number": "string",
  "first_name": "string",
  "last_name": "string",
  "phone_number": "string",
  "citizenship": "string",
  "country_of_birth": "string",
  "date_of_birth": "string",
  "video_identification_completed_at": "string",
  "place_of_birth": "string",
  "family_status": "string",
  "gender": "string",
  "not_us_income_tax": true,
  "trading_on_behalf_of_self": true,
  "title": "string",
  "name_affix": "string",
  "mifid_status": "skipped",
  "name_at_birth": "string",
  "second_citizenship": "string",
  "country_of_taxation": "string",
  "second_country_of_taxation": "string",
  "second_tax_id_number": "string",
  "share": 42.0,
  "sole_right_of_representation": true,
  "exclusively_taxable_in_country_of_taxation": true,
  "type": "string",
  "video_identification_completed": true,
  "address": {
    "id": "string",
    "street_additional": "string",
    "city": "string",
    "country": "string",
    "state": "string",
    "street": "string",
    "number": "string",
    "zipcode": "string"
  },
  "video_identifications": [
    {
      "id": "string",
      "identity_id": "string",
      "idnow_id": "string",
      "redirect_url": "string",
      "statuses": [
        "string"
      ],
      "data": {},
      "url": "string",
      "has_files": true,
      "completed": true,
      "success": true,
      "rejected": true,
      "pending": true,
      "reason": "string",
      "identificationtime": "string",
      "status": "string"
    }
  ],
  "attachments": [
    {
      "id": "string",
      "file": {},
      "filename": "string",
      "document_type": "string",
      "document_id_number": "string",
      "issued_at": "string",
      "expires_at": "string",
      "issuing_authority": "string",
      "issuing_country": "string",
      "content_type": "string"
    }
  ],
  "term": {
    "custody_wallet_terms_acceptance": true,
    "custody_wallet_privacy_acceptance": true
  }
}

Fetch the configuration data

GET /config

Fetch the configuration data, like timezone and supported countries for the current user.

Responses

GET /config
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/config
Response example (200)
[
  {
    "timezone": "string",
    "supported_countries": [
      "string"
    ]
  }
]

custody

Custody endpoints describe how to create and access custody account holders, custody accounts and transactions.

Custody assets are the starting point, each user can only have one custody account per asset. Assets are created by Bitbond at the request of the custody partner. Once an asset has been created a list of all the partner's assets can be fetched with the /custody_assets endpoint.

To create a custody account for a user you will need the asset ID you wish to create the account for. Once the user has a custody account it is possible to fetch their transactions and create new transactions for the relevant asset.

Assets

GET /custody_assets

Assets

Responses

GET /custody_assets
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/custody_assets
Response example (200)
[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "wallet_id": "string",
    "network": "string",
    "code": "string",
    "issuer_address": "string",
    "url": "string",
    "details": {}
  }
]

User account holders

GET /users/{user_id}/custody_account_holders

User account holders

Path parameters

Responses

GET /users/{user_id}/custody_account_holders
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/custody_account_holders
Response example (200)
[
  {
    "id": "string",
    "internal_id": "string",
    "name": "string",
    "email": "string",
    "kyc_data": {
      "address": {
        "id": "string",
        "street_additional": "string",
        "city": "string",
        "country": "string",
        "state": "string",
        "street": "string",
        "number": "string",
        "zipcode": "string"
      },
      "identity": {
        "id": "string",
        "user_id": "string",
        "company_role": "string",
        "tax_id_number": "string",
        "first_name": "string",
        "last_name": "string",
        "phone_number": "string",
        "citizenship": "string",
        "country_of_birth": "string",
        "date_of_birth": "string",
        "video_identification_completed_at": "string",
        "place_of_birth": "string",
        "family_status": "string",
        "gender": "string",
        "not_us_income_tax": true,
        "trading_on_behalf_of_self": true,
        "title": "string",
        "name_affix": "string",
        "mifid_status": "skipped",
        "name_at_birth": "string",
        "second_citizenship": "string",
        "country_of_taxation": "string",
        "second_country_of_taxation": "string",
        "second_tax_id_number": "string",
        "share": 42.0,
        "sole_right_of_representation": true,
        "exclusively_taxable_in_country_of_taxation": true,
        "type": "string",
        "video_identification_completed": true,
        "address": {
          "id": "string",
          "street_additional": "string",
          "city": "string",
          "country": "string",
          "state": "string",
          "street": "string",
          "number": "string",
          "zipcode": "string"
        },
        "video_identifications": [
          {
            "id": "string",
            "identity_id": "string",
            "idnow_id": "string",
            "redirect_url": "string",
            "statuses": [
              "string"
            ],
            "data": {},
            "url": "string",
            "has_files": true,
            "completed": true,
            "success": true,
            "rejected": true,
            "pending": true,
            "reason": "string",
            "identificationtime": "string",
            "status": "string"
          }
        ],
        "attachments": [
          {
            "id": "string",
            "file": {},
            "filename": "string",
            "document_type": "string",
            "document_id_number": "string",
            "issued_at": "string",
            "expires_at": "string",
            "issuing_authority": "string",
            "issuing_country": "string",
            "content_type": "string"
          }
        ],
        "term": {
          "custody_wallet_terms_acceptance": true,
          "custody_wallet_privacy_acceptance": true
        }
      },
      "idnow_id": "string"
    },
    "idnow_id": "string",
    "accounts": [
      {
        "id": "string",
        "account_holder_id": "string",
        "wallet_address_id": "string",
        "address": "string",
        "asset": {
          "id": "string",
          "name": "string",
          "description": "string",
          "wallet_id": "string",
          "network": "string",
          "code": "string",
          "issuer_address": "string",
          "url": "string",
          "details": {}
        }
      }
    ]
  }
]

User account holder

POST /users/{user_id}/custody_account_holders

User account holder

Path parameters

Responses

POST /users/{user_id}/custody_account_holders
curl \
 -X POST https://client-subdomain.bitbond.net/api/v1/users/{user_id}/custody_account_holders
Response example (201)
{
  "id": "string",
  "internal_id": "string",
  "name": "string",
  "email": "string",
  "kyc_data": {
    "address": {
      "id": "string",
      "street_additional": "string",
      "city": "string",
      "country": "string",
      "state": "string",
      "street": "string",
      "number": "string",
      "zipcode": "string"
    },
    "identity": {
      "id": "string",
      "user_id": "string",
      "company_role": "string",
      "tax_id_number": "string",
      "first_name": "string",
      "last_name": "string",
      "phone_number": "string",
      "citizenship": "string",
      "country_of_birth": "string",
      "date_of_birth": "string",
      "video_identification_completed_at": "string",
      "place_of_birth": "string",
      "family_status": "string",
      "gender": "string",
      "not_us_income_tax": true,
      "trading_on_behalf_of_self": true,
      "title": "string",
      "name_affix": "string",
      "mifid_status": "skipped",
      "name_at_birth": "string",
      "second_citizenship": "string",
      "country_of_taxation": "string",
      "second_country_of_taxation": "string",
      "second_tax_id_number": "string",
      "share": 42.0,
      "sole_right_of_representation": true,
      "exclusively_taxable_in_country_of_taxation": true,
      "type": "string",
      "video_identification_completed": true,
      "address": {
        "id": "string",
        "street_additional": "string",
        "city": "string",
        "country": "string",
        "state": "string",
        "street": "string",
        "number": "string",
        "zipcode": "string"
      },
      "video_identifications": [
        {
          "id": "string",
          "identity_id": "string",
          "idnow_id": "string",
          "redirect_url": "string",
          "statuses": [
            "string"
          ],
          "data": {},
          "url": "string",
          "has_files": true,
          "completed": true,
          "success": true,
          "rejected": true,
          "pending": true,
          "reason": "string",
          "identificationtime": "string",
          "status": "string"
        }
      ],
      "attachments": [
        {
          "id": "string",
          "file": {},
          "filename": "string",
          "document_type": "string",
          "document_id_number": "string",
          "issued_at": "string",
          "expires_at": "string",
          "issuing_authority": "string",
          "issuing_country": "string",
          "content_type": "string"
        }
      ],
      "term": {
        "custody_wallet_terms_acceptance": true,
        "custody_wallet_privacy_acceptance": true
      }
    },
    "idnow_id": "string"
  },
  "idnow_id": "string",
  "accounts": [
    {
      "id": "string",
      "account_holder_id": "string",
      "wallet_address_id": "string",
      "address": "string",
      "asset": {
        "id": "string",
        "name": "string",
        "description": "string",
        "wallet_id": "string",
        "network": "string",
        "code": "string",
        "issuer_address": "string",
        "url": "string",
        "details": {}
      }
    }
  ]
}

User account holder

GET /users/{user_id}/custody_account_holders/{id}

User account holder

Path parameters

Responses

GET /users/{user_id}/custody_account_holders/{id}
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/custody_account_holders/{id}
Response example (200)
{
  "id": "string",
  "internal_id": "string",
  "name": "string",
  "email": "string",
  "kyc_data": {
    "address": {
      "id": "string",
      "street_additional": "string",
      "city": "string",
      "country": "string",
      "state": "string",
      "street": "string",
      "number": "string",
      "zipcode": "string"
    },
    "identity": {
      "id": "string",
      "user_id": "string",
      "company_role": "string",
      "tax_id_number": "string",
      "first_name": "string",
      "last_name": "string",
      "phone_number": "string",
      "citizenship": "string",
      "country_of_birth": "string",
      "date_of_birth": "string",
      "video_identification_completed_at": "string",
      "place_of_birth": "string",
      "family_status": "string",
      "gender": "string",
      "not_us_income_tax": true,
      "trading_on_behalf_of_self": true,
      "title": "string",
      "name_affix": "string",
      "mifid_status": "skipped",
      "name_at_birth": "string",
      "second_citizenship": "string",
      "country_of_taxation": "string",
      "second_country_of_taxation": "string",
      "second_tax_id_number": "string",
      "share": 42.0,
      "sole_right_of_representation": true,
      "exclusively_taxable_in_country_of_taxation": true,
      "type": "string",
      "video_identification_completed": true,
      "address": {
        "id": "string",
        "street_additional": "string",
        "city": "string",
        "country": "string",
        "state": "string",
        "street": "string",
        "number": "string",
        "zipcode": "string"
      },
      "video_identifications": [
        {
          "id": "string",
          "identity_id": "string",
          "idnow_id": "string",
          "redirect_url": "string",
          "statuses": [
            "string"
          ],
          "data": {},
          "url": "string",
          "has_files": true,
          "completed": true,
          "success": true,
          "rejected": true,
          "pending": true,
          "reason": "string",
          "identificationtime": "string",
          "status": "string"
        }
      ],
      "attachments": [
        {
          "id": "string",
          "file": {},
          "filename": "string",
          "document_type": "string",
          "document_id_number": "string",
          "issued_at": "string",
          "expires_at": "string",
          "issuing_authority": "string",
          "issuing_country": "string",
          "content_type": "string"
        }
      ],
      "term": {
        "custody_wallet_terms_acceptance": true,
        "custody_wallet_privacy_acceptance": true
      }
    },
    "idnow_id": "string"
  },
  "idnow_id": "string",
  "accounts": [
    {
      "id": "string",
      "account_holder_id": "string",
      "wallet_address_id": "string",
      "address": "string",
      "asset": {
        "id": "string",
        "name": "string",
        "description": "string",
        "wallet_id": "string",
        "network": "string",
        "code": "string",
        "issuer_address": "string",
        "url": "string",
        "details": {}
      }
    }
  ]
}

User accounts

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts

User accounts

Path parameters

Responses

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts
Response example (200)
[
  {
    "id": "string",
    "account_holder_id": "string",
    "wallet_address_id": "string",
    "address": "string",
    "asset": {
      "id": "string",
      "name": "string",
      "description": "string",
      "wallet_id": "string",
      "network": "string",
      "code": "string",
      "issuer_address": "string",
      "url": "string",
      "details": {}
    }
  }
]

User account

POST /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts

User account

Path parameters

Body Required

Custody asset information

Responses

POST /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts
curl \
 -X POST https://client-subdomain.bitbond.net/api/v1/users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts \
 -H "Content-Type: application/json" \
 -d '{"custody_account":{"asset_id":"string"}}'
Request example
{
  "custody_account": {
    "asset_id": "string"
  }
}
Response example (201)
{
  "id": "string",
  "account_holder_id": "string",
  "wallet_address_id": "string",
  "address": "string",
  "asset": {
    "id": "string",
    "name": "string",
    "description": "string",
    "wallet_id": "string",
    "network": "string",
    "code": "string",
    "issuer_address": "string",
    "url": "string",
    "details": {}
  }
}

User account

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{id}

User account

Path parameters

Responses

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{id}
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{id}
Response example (200)
{
  "id": "string",
  "account_holder_id": "string",
  "wallet_address_id": "string",
  "address": "string",
  "asset": {
    "id": "string",
    "name": "string",
    "description": "string",
    "wallet_id": "string",
    "network": "string",
    "code": "string",
    "issuer_address": "string",
    "url": "string",
    "details": {}
  }
}

Account balance

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{id}/balance

Account balance

Path parameters

Responses

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{id}/balance
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{id}/balance
Response example (200)
{
  "account_id": "string",
  "balance": 42.0
}

Account transactions

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions

Account transactions

Path parameters

Query parameters

  • limit number Required

    Number of transactions to return.

  • order string

    Order of transactions by timestamp (asc or desc).

  • offset string

    Offset by which to fetch transactions from.

  • cursor number

    Transaction cursor to start fetching from.

Responses

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions?limit=42.0
Response example (200)
[
  {
    "id": "string",
    "amount": 42.0,
    "from_address": "string",
    "destination_address": "string",
    "reference": "string",
    "asset_code": "string",
    "asset_issuer": "string",
    "tx_hash": "string",
    "confirmed_at": "string",
    "failed_at": "string",
    "created_at": "string",
    "status": "string",
    "cursor": 42
  }
]

Transaction

POST /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions

Transaction. The idem_key attribute needs to be unique to guard against double submissions.

Path parameters

Body Required

Withdrawal transaction information

Responses

POST /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions
curl \
 -X POST https://client-subdomain.bitbond.net/api/v1/users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions \
 -H "Content-Type: application/json" \
 -d '{"transaction":{"amount":42.0,"destination_address":"string","idem_key":"string","reference":"string"}}'
Request example
{
  "transaction": {
    "amount": 42.0,
    "destination_address": "string",
    "idem_key": "string",
    "reference": "string"
  }
}
Response example (201)
{
  "id": "string",
  "amount": 42.0,
  "from_address": "string",
  "destination_address": "string",
  "reference": "string",
  "asset_code": "string",
  "asset_issuer": "string",
  "tx_hash": "string",
  "confirmed_at": "string",
  "failed_at": "string",
  "created_at": "string",
  "status": "string",
  "cursor": 42
}

Account transaction with specific ID

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/{id}

Account transaction with specific ID

Path parameters

Responses

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/{id}
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/{id}
Response example (200)
{
  "id": "string",
  "amount": 42.0,
  "from_address": "string",
  "destination_address": "string",
  "reference": "string",
  "asset_code": "string",
  "asset_issuer": "string",
  "tx_hash": "string",
  "confirmed_at": "string",
  "failed_at": "string",
  "created_at": "string",
  "status": "string",
  "cursor": 42
}

Withdrawable balance

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions/withdrawable_balance

Withdrawable balance

Path parameters

Responses

  • 200 number

    Returns the withdrawable balance.

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions/withdrawable_balance
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions/withdrawable_balance
Response example (200)
42.0

Estimated fee

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions/estimated_fee

Estimated fee

Path parameters

Responses

  • 200 number

    Returns the estimated fee.

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions/estimated_fee
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_accounts/{custody_account_id}/transactions/estimated_fee
Response example (200)
42.0

Balances

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_balances

Balances

Path parameters

Responses

GET /users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_balances
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/custody_account_holders/{custody_account_holder_id}/custody_balances
Response example (200)
[
  {
    "account_id": "string",
    "balance": 42.0
  }
]

Add a file attachment to the identity

POST /users/{user_id}/kyc/identities/{id}/file/{type}/{number}

Add a file attachment to the identity.

Path parameters

  • user_id string Required

    User id

  • id string Required

    Resource ID

  • type string Required

    File type

    Values are commercial_register, authorization, or legal_structure.

  • number string Required

    Document ID number

Query parameters

Body Required

The identity file information

Responses

POST /users/{user_id}/kyc/identities/{id}/file/{type}/{number}
curl \
 -X POST https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/identities/{id}/file/{type}/{number}?issued_at=string&expires_at=string&issuing_authority=string&issuing_country=string \
 -H "Content-Type: application/json" \
 -d '{"attachment":{}}'
Request example
{
  "attachment": {}
}
Response example (201)
{
  "id": "string",
  "file": {},
  "filename": "string",
  "document_type": "string",
  "document_id_number": "string",
  "issued_at": "string",
  "expires_at": "string",
  "issuing_authority": "string",
  "issuing_country": "string",
  "content_type": "string"
}

Fetch the list of the identity file attachments

GET /users/{user_id}/kyc/identities/{id}/file

Fetch the list of the identity file attachments.

Path parameters

Responses

GET /users/{user_id}/kyc/identities/{id}/file
curl \
 -X GET https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/identities/{id}/file
Response example (200)
[
  {
    "id": "string",
    "file": {},
    "filename": "string",
    "document_type": "string",
    "document_id_number": "string",
    "issued_at": "string",
    "expires_at": "string",
    "issuing_authority": "string",
    "issuing_country": "string",
    "content_type": "string"
  }
]

Add file attachment to the current business

POST /users/{user_id}/kyc/businesses/file/{type}

Add file attachment to the current business.

Path parameters

  • user_id string Required

    User id

  • type string Required

    File type

    Values are commercial_register, authorization, or legal_structure.

Body Required

The business file information

Responses

POST /users/{user_id}/kyc/businesses/file/{type}
curl \
 -X POST https://client-subdomain.bitbond.net/api/v1/users/{user_id}/kyc/businesses/file/{type} \
 -H "Content-Type: application/json" \
 -d '{"attachment":{}}'
Request example
{
  "attachment": {}
}
Response example (201)