Horizon (3.11.0)

Download OpenAPI specification:Download

Support: [email protected] URL: https://tokend.io License: Apache 2.0

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

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: 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

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

Content type

application/vnd.api+json

Copy

Expand all Collapse all


{"data": 
{"id": "GBSR6JG5AYSAW7HK6EGJFYVIVN54LVGSY3ZLJ6X3IBQZ766EJABCZQTH",
"type": "accounts",
"attributes": 
{"kyc_recovery_status": 
{"value": 1,
"name": "General"
}
},
"relationships": 
{"signers": 
{"data": 
[
{"id": "GBSR6JG5AYSAW7HK6EGJFYVIVN54LVGSY3ZLJ6X3IBQZ766EJABCZQTH",
"type": "signers"
}
]
},
"referrer": 
{"data": 
{"id": "GBSR6JG5AYSAW7HK6EGJFYVIVN54LVGSY3ZLJ6X3IBQZ766EJABCZQTH",
"type": "accounts"
}
},
"balances": 
{"data": 
[
{"id": "BDLXKLLVS6UIQEDYCZKIC5222GGQLCOTHM4BWXVCBDQMJTUWUFUATV2Q",
"type": "balances"
}
]
},
"limits": 
{"data": 
[
{"id": "1",
"type": "limits"
}
]
},
"external_system_ids": 
{"data": 
[
{"id": "1",
"type": "external-system-ids"
}
]
},
"role": 
{"data": 
{"id": "4581",
"type": "account-roles"
}
},
"fees": 
{"data": 
[
{"id": "a343e3cbcc72928a571778f77bf2554eb5b72c79ce28bbc9d3325c60c21e5241",
"type": "fees"
}
]
},
"limits_with_stats": 
{"data": 
[
{"id": "1",
"type": "limits-with-stats"
}
]
},
"kyc_data": 
{"data": 
{"id": "GBSR6JG5AYSAW7HK6EGJFYVIVN54LVGSY3ZLJ6X3IBQZ766EJABCZQTH",
"type": "account-kyc"
}
}
}
},
"included": 
[
{"id": "GBSR6JG5AYSAW7HK6EGJFYVIVN54LVGSY3ZLJ6X3IBQZ766EJABCZQTH",
"type": "accounts",
"attributes": 
{"kyc_recovery_status": 
{"value": 1,
"name": "General"
}
},
"relationships": 
{"signers": 
{"data": 
[
{"id": "GBSR6JG5AYSAW7HK6EGJFYVIVN54LVGSY3ZLJ6X3IBQZ766EJABCZQTH",
"type": "signers"
}
]
},
"referrer": 
{"data": 
{"id": "GBSR6JG5AYSAW7HK6EGJFYVIVN54LVGSY3ZLJ6X3IBQZ766EJABCZQTH",
"type": "accounts"
}
},
"balances": 
{"data": 
[
{"id": "BDLXKLLVS6UIQEDYCZKIC5222GGQLCOTHM4BWXVCBDQMJTUWUFUATV2Q",
"type": "balances"
}
]
},
"limits": 
{"data": 
[
{"id": "1",
"type": "limits"
}
]
},
"external_system_ids": 
{"data": 
[
{"id": "1",
"type": "external-system-ids"
}
]
},
"role": 
{"data": 
{"id": "4581",
"type": "account-roles"
}
},
"fees": 
{"data": 
[
{"id": "a343e3cbcc72928a571778f77bf2554eb5b72c79ce28bbc9d3325c60c21e5241",
"type": "fees"
}
]
},
"limits_with_stats": 
{"data": 
[
{"id": "1",
"type": "limits-with-stats"
}
]
},
"kyc_data": 
{"data": 
{"id": "GBSR6JG5AYSAW7HK6EGJFYVIVN54LVGSY3ZLJ6X3IBQZ766EJABCZQTH",
"type": "account-kyc"
}
}
}
}
]
}

Accounts list

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

query Parameters

filter[account]	Array of strings Filters accounts by account id
filter[role]	Array of integers Filters accounts by role id
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.