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.


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.


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:


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:


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)"


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

Unique identifier of an account

query Parameters
Enum: "fees" "balances" "balances.asset" "balances.state" "referrer" "limits" "external_system_ids" "role" "role.rules" "kyc_data"
Example: include=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



account exists


bad input parameter


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


such an account does not exist

get /v3/accounts/{id}

TokenD Developer Environment


Response samples

Content type
Expand all Collapse all
  • "data":
  • "included":

Accounts list

Allows to get list of accounts. Admin signature is required.

query Parameters
Array of strings

Filters accounts by account id

Array of integers

Filters accounts by role id

integer >= 0

Page number to return.

integer [ 1 .. 100 ]
Default: 15

Numbers of items per page to return.

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.



asset exists


bad input parameter

get /v3/accounts

TokenD Developer Environment


Response samples

Content type
Expand all Collapse all
  • "data":