Horizon (3.5.1)

Download OpenAPI specification:Download

Horizon is the client-facing REST API module that consumes data from the core of the system and makes it more convenient to use the client facing application. It allows submitting transactions to the network, reading history of operations, and checking the state of entities.

IMPORTANT: Note that endpoints not specified in this document or marked as WIP do not guaranty the backwards compability maintenance.

Overview

Horizon uses JSON:API convention to format requests and responses. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Security

TokenD uses the Ed25519 algorithm for authorizing any request or read private data. The use of such cryptographic proof allows building a system where transfer of secrets in an open form is not necessary, which significantly improves the security. Thus, an attacker who has access to one of the servers will not be able to compromise users' secrets.

Request signature implementation is based on IETF HTTP Signatures draft RFC. Implicit headers parameter is not supported; clients must explicitly specify headers used for signing.

The signature algorithm supported is ed25519-sha256, which uses public signer key as keyId.

Both Signature and Authorization HTTP authentication schemas are supported.

The minimum recommended data to sign is the (request-header) and date.

For the following request:

GET /users?type=2 HTTP/1.1
Host: api.tokend.io
Date: Fri, 05 Jan 2018 21:31:40 GMT

Signing string would be:

date: Fri, 05 Jan 2018 21:31:40 GMT
(request-target): get /users?type=2

Note that header names and HTTP method are lowercased.

The next step is to convert the signing string to a byte array using UTF-8 encoding and to take its SHA-256 hash.

For the signing string above, hash would be:

6fcbee4b0a8932784644d33b360bd3eef389ed37dfd66f17e4bfa910ba9d616a

Now, you have to sign hash with a private key and encode the result in Base64. For a seed such as SCDMOOXVNMO6SA22AYUMZDIGLDJMBUTVEGB73FFNTLFJILBJWIU4NQ3D, the encoded signature would be:

w/y3EsliTmQPC6MS88N/kjU/hFVxlIdhFhzfRGv4yIsSokgMpxVqxcC/CmUsAN4t3BKpskGG7+JEWryV8NXvCg==

The result HTTP header included to the request then would be:

Authorization: keyId="GBLTOG6EJS5OWDNQNSCEAVDNMPBY6F73XZHHKR27YE5AKE23ZZEXOLBK",algorithm="ed25519-sha256",signature="w/y3EsliTmQPC6MS88N/kjU/hFVxlIdhFhzfRGv4yIsSokgMpxVqxcC/CmUsAN4t3BKpskGG7+JEWryV8NXvCg==",headers="date (request-target)"

Accounts

Defines access points for accounts and related entities

Account by ID

Allows getting Account with corresponding details.

Note that if we include fees filter - we will receive all the fees applied to a particular account.

For example if someone's, say Bob, account has a several fees applied to itself:

  • first fee applied globally for all accounts for payments of amount from 0 to 100 BTC and is 1% from the payment
  • second fee applied exactly to Bob's account and is 2% of the payment of amounts from 100 to 200 BTC

then we will receive both of them in response because they are applied to Bob's account

path Parameters
id
required
string

Unique identifier of an account

query Parameters
include
string
Enum:"fees" "balances" "balances.asset" "balances.state" "referrer" "limits" "external_system_ids" "role" "role.rules" "kyc_data"
Example: "balances,balances.asset"

🔒 Following relationships require an owner's or admin's signature to be included:

  • balances.state
  • referrer
  • fees
  • role
  • role.rules
  • limits
  • external_system_ids
  • kyc_data

Responses

200

account exists

400

bad input parameter

401

either an invalid signature has been provided or a signer has not been authorized to access specified resources

404

such an account does not exist

get /v3/accounts/{id}

TokenD Developer Environment

https://api.achilles.tokend.io/v3/accounts/{id}

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    {
    },
  • "included":
    [
    ]
}

Calculate fee

Allows calculating a fee for an account.

path Parameters
asset
required
string

Unique identifier of an asset

fee_type
required
integer

Type of fee

subtype
required
integer

Subtype of fee

amount
required
string

Amount to calculate on which fee is based on

Responses

200

fee does exist and is calculated successfuly

400

bad input parameter

500

internal error occured during the request processing

get /v3/accounts/{id}/calculated_fees

TokenD Developer Environment

https://api.achilles.tokend.io/v3/accounts/{id}/calculated_fees

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Signers for Account

Allows getting Signers of the account with corresponding details.

path Parameters
id
required
string

Unique identifier of an account

query Parameters
include
string
Enum:"role" "role.rules"
Example: "role,role.rules"

For signers, following relationships can be included:

Responses

200

account exists

400

bad input parameter

404

such an account does not exist

get /v3/accounts/{id}/signers

TokenD Developer Environment

https://api.achilles.tokend.io/v3/accounts/{id}/signers

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "included":
    [
    ],
  • "links":
    {
    }
}

Assets

Defines access points for assets

Asset by ID

Allows getting Asset with corresponding details.

path Parameters
id
required
string

Unique identifier of an asset (code)

query Parameters
include
string
Value:"owner"

Relationships that may be used for the included parameter.

Responses

200

asset exists

400

bad input parameter

404

asset does not exist

get /v3/assets/{id}

TokenD Developer Environment

https://api.achilles.tokend.io/v3/assets/{id}

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    {
    },
  • "included":
    [
    ]
}

Asset List

Allows getting a filtered list of Asset with corresponding details.

query Parameters
filter[policy]
integer

Filters assets by a specified bit mask. Returns the page of assets where at least one bit intersects

filter[owner]
string

Filters assets by a specified owner's account address.

include
string
Value:"owner"

Relationships that may be used for the included parameter.

page[number]
integer >= 0

Page number to return.

page[limit]
integer [ 1 .. 100 ]
Default: 15

Numbers of items per page to return.

page[order]
string
Default: "asc"
Enum:"asc" "desc"

Order of records on the page. If sortingParam is not specified, order of records is by default sorted by ID.

Responses

200

asset exists

400

bad input parameter

404

asset does not exist

get /v3/assets

TokenD Developer Environment

https://api.achilles.tokend.io/v3/assets

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "included":
    [
    ],
  • "links":
    {
    }
}

Asset Creation Request by ID

Allows getting CreateAssetRequest by ID

🔒 Requestor's or reviewer's signature is needed

query Parameters
filter[requestor]
string

Filters requests by requestor - source of the operation.

filter[reviewer]
string

Filters requests by reviewer - account assigned to review requests.

filter[state]
integer [ 1 .. 5 ]

Filters requests by their state.

  • 1 - pending
  • 2 - canceled
  • 3 - approved
  • 4 - rejected
  • 5 - permanently_rejected
filter[pending_tasks]
integer

Filters requests by existing tasks in pending tasks bit mask. Returns requests if all bits are set.

filter[pending_tasks_not_set]
integer

Filters requests by existing tasks in pending tasks bit mask. Returns requests if none of bits is set.

filter[pending_tasks_any_of]
integer

Filters requests by existing tasks in pending tasks bit mask. Returns requests if at least one bit is set.

filter[request_details.asset]
string

Filters asset create requests by asset code.

include
string
Enum:"request_details" "request_details.asset"

Relationships that may be used for the included parameter.

Responses

200

requests exist

400

bad input parameter

401

either an invalid signature has been provided or a signer has not been authorized to access specified resources

404

request does not exist

get /v3/create_asset_requests/{id}

TokenD Developer Environment

https://api.achilles.tokend.io/v3/create_asset_requests/{id}

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    {
    },
  • "included":
    [
    ]
}

Asset Creation Request List

Allows getting a filtered list of CreateAssetRequest with details

🔒 Requestor's or reviewer's signature is needed

query Parameters
filter[requestor]
string

Filters requests by requestor - source of the operation.

filter[reviewer]
string

Filters requests by reviewer - account assigned to review requests.

filter[state]
integer [ 1 .. 5 ]

Filters requests by their state.

  • 1 - pending
  • 2 - canceled
  • 3 - approved
  • 4 - rejected
  • 5 - permanently_rejected
filter[pending_tasks]
integer

Filters requests by existing tasks in pending tasks bit mask. Returns requests if all bits are set.

filter[pending_tasks_not_set]
integer

Filters requests by existing tasks in pending tasks bit mask. Returns requests if none of bits is set.

filter[pending_tasks_any_of]
integer

Filters requests by existing tasks in pending tasks bit mask. Returns requests if at least one bit is set.

filter[request_details.asset]
string

Filters asset create requests by asset code.

include
string
Enum:"request_details" "request_details.asset"

Relationships that may be used for the included parameter.

page[number]
integer >= 0

Page number to return.

page[limit]
integer [ 1 .. 100 ]
Default: 15

Numbers of items per page to return.

page[order]
string
Default: "asc"
Enum:"asc" "desc"

Order of records on the page. If sortingParam is not specified, order of records is by default sorted by ID.

Responses

200

requests exist

400

bad input parameter

401

either an invalid signature has been provided or a signer has not been authorized to access specified resources

404

requests do not exist

get /v3/create_asset_requests

TokenD Developer Environment

https://api.achilles.tokend.io/v3/create_asset_requests

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "included":
    [
    ],
  • "links":
    {
    }
}

Update Asset Request by ID

Allows getting UpdateAssetRequest by ID

🔒 Requestor's or reviewer's signature is needed

query Parameters
filter[requestor]
string

Filters requests by requestor - source of the operation.

filter[reviewer]
string

Filters requests by reviewer - account assigned to review requests.

filter[state]
integer [ 1 .. 5 ]

Filters requests by their state.

  • 1 - pending
  • 2 - canceled
  • 3 - approved
  • 4 - rejected
  • 5 - permanently_rejected
filter[pending_tasks]
integer

Filters requests by existing tasks in pending tasks bit mask. Returns requests if all bits are set.

filter[pending_tasks_not_set]
integer

Filters requests by existing tasks in pending tasks bit mask. Returns requests if none of bits is set.

filter[pending_tasks_any_of]
integer

Filters requests by existing tasks in pending tasks bit mask. Returns requests if at least one bit is set.

filter[request_details.asset]
string

Filters update asset requests by asset code.

include
string
Enum:"request_details" "request_details.asset"

Relationships that may be used for the included parameter.

Responses

200

requests exist

400

bad input parameter

401

either an invalid signature has been provided or a signer has not been authorized to access specified resources

404

request does not exist

get /v3/update_asset_requests/{id}

TokenD Developer Environment

https://api.achilles.tokend.io/v3/update_asset_requests/{id}

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    {
    },
  • "included":
    [
    ]
}

Update Asset Request List

Allows getting a filtered list of UpdateAssetRequest with details

🔒 Requestor's or reviewer's signature is needed

query Parameters
filter[requestor]
string

Filters requests by requestor - source of the operation.

filter[reviewer]
string

Filters requests by reviewer - account assigned to review requests.

filter[state]
integer [ 1 .. 5 ]

Filters requests by their state.

  • 1 - pending
  • 2 - canceled
  • 3 - approved
  • 4 - rejected
  • 5 - permanently_rejected
filter[pending_tasks]
integer

Filters requests by existing tasks in pending tasks bit mask. Returns requests if all bits are set.

filter[pending_tasks_not_set]
integer

Filters requests by existing tasks in pending tasks bit mask. Returns requests if none of bits is set.

filter[pending_tasks_any_of]
integer

Filters requests by existing tasks in pending tasks bit mask. Returns requests if at least one bit is set.

filter[request_details.asset]
string

Filters asset update requests by asset code.

include
string
Enum:"request_details" "request_details.asset"

Relationships that may be used for the included parameter.

page[number]
integer >= 0

Page number to return.

page[limit]
integer [ 1 .. 100 ]
Default: 15

Numbers of items per page to return.

page[order]
string
Default: "asc"
Enum:"asc" "desc"

Order of records on the page. If sortingParam is not specified, order of records is by default sorted by ID.

Responses

200

requests exist

400

bad input parameter

401

either an invalid signature has been provided or a signer has not been authorized to access specified resources

404

requests do not exist

get /v3/asset_update_requests

TokenD Developer Environment

https://api.achilles.tokend.io/v3/asset_update_requests

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    [
    ],
  • "included":
    [
    ],
  • "links":
    {
    }
}

Balances

Balance by ID

Allows getting Balance with corresponding details.

path Parameters
id
required
string

Unique identifier of a balance

query Parameters
include
string
Enum:"asset" "state"
Example: "asset"

🔒 Following relationships require an owner's or admin's signature to be included:

  • state