Skip to main content

Ledger API

API docs by Redocly

Ledger API (v1.7.4)

Download OpenAPI specification:Download

server

Show server information.

Authorizations:
basicAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

accounts

List accounts from a ledger.

List accounts from a ledger, sorted by address in descending order.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

query Parameters
page_size
integer [ 1 .. 1000 ]
Default: 15
Example: page_size=100

The maximum number of results to return per page

after
string
Example: after=users:003

Pagination cursor, will return accounts after given address, in descending order.

address
string
Example: address=users:.+

Filter accounts by address pattern (regular expression placed between ^ and $).

metadata
object
Example:

Filter accounts by metadata key value pairs. Nested objects can be used as seen in the example below.

balance
integer <int64>
Example: balance=2400

Filter accounts by their balance (default operator is gte)

balance_operator
string
Enum: "gte" "lte" "gt" "lt" "e"
Example: balance_operator=gte

Operator used for the filtering of balances can be greater than/equal, less than/equal, greater than, less than, or equal

pagination_token
string
Example: pagination_token=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ==

Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when the pagination token is set.

Responses

Response samples

Content type
application/json
{
  • "cursor": null
}

Count the accounts from a ledger.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

query Parameters
address
string
Example: address=users:.+

Filter accounts by address pattern (regular expression placed between ^ and $).

metadata
object
Example:

Filter accounts by metadata key value pairs. Nested objects can be used as seen in the example below.

Responses

Get account by its address.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

address
required
string
Example: users:001

Exact address of the account. It must match the following regular expressions pattern:

^\w+(:\w+)*$

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Add metadata to an account.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

address
required
string
Example: users:001

Exact address of the account. It must match the following regular expressions pattern:

^\w+(:\w+)*$
Request Body schema: application/json

metadata

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "admin": true,
  • "a": {
    }
}

Response samples

Content type
application/json
{
  • "error_code": "VALIDATION",
  • "error_message": "invalid account address format"
}

mapping

Get the mapping of a ledger.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update the mapping of a ledger.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

Request Body schema: application/json
required
Array of objects (Contract)
Array
account
string
expr
required
object

Responses

Request samples

Content type
application/json
{
  • "contracts": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

script

Execute a Numscript.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

query Parameters
preview
boolean
Example: preview=true

Set the preview mode. Preview mode doesn't add the logs to the database or publish a message to the message broker.

Request Body schema: application/json
reference
string

Reference to attach to the generated transaction

object or null
plain
required
string
vars
object

Responses

Request samples

Content type
application/json
{
  • "reference": "order_1234",
  • "metadata": {
    },
  • "plain": "vars {\naccount $user\n}\nsend [COIN 10] (\n\tsource = @world\n\tdestination = $user\n)\n",
  • "vars": {
    }
}

Response samples

Content type
application/json
{
  • "error_message": "error_message",
  • "details": "details",
  • "error_code": "INTERNAL",
  • "transaction": {
    }
}

stats

Get Stats

Get ledger stats (aggregate metrics on accounts and transactions) The stats for account

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

name of the ledger

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

transactions

List transactions from a ledger.

List transactions from a ledger, sorted by txid in descending order.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

query Parameters
page_size
integer [ 1 .. 1000 ]
Default: 15
Example: page_size=100

The maximum number of results to return per page

after
string
Example: after=1234

Pagination cursor, will return transactions after given txid (in descending order).

reference
string
Example: reference=ref:001

Find transactions by reference field.

account
string
Example: account=users:001

Find transactions with postings involving given account, either as source or destination.

source
string
Example: source=users:001

Find transactions with postings involving given account at source.

destination
string
Example: destination=users:001

Find transactions with postings involving given account at destination.

start_time
string

Filter transactions that occurred after this timestamp. The format is RFC3339 and is inclusive (for example, 12:00:01 includes the first second of the minute).

end_time
string

Filter transactions that occurred before this timestamp. The format is RFC3339 and is exclusive (for example, 12:00:01 excludes the first second of the minute).

pagination_token
string
Example: pagination_token=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ==

Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when the pagination token is set.

metadata
object
Example:

Filter transactions by metadata key value pairs. Nested objects can be used as seen in the example below.

Responses

Response samples

Content type
application/json
{
  • "cursor": null
}

Count the transactions from a ledger.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

query Parameters
reference
string
Example: reference=ref:001

Filter transactions by reference field.

account
string
Example: account=users:001

Filter transactions with postings involving given account, either as source or destination (regular expression placed between ^ and $).

source
string
Example: source=users:001

Filter transactions with postings involving given account at source (regular expression placed between ^ and $).

destination
string
Example: destination=users:001

Filter transactions with postings involving given account at destination (regular expression placed between ^ and $).

metadata
object
Example:

Filter transactions by metadata key value pairs. Nested objects can be used as seen in the example below.

Responses

Create a new transaction to a ledger.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

query Parameters
preview
boolean
Example: preview=true

Set the preview mode. Preview mode doesn't add the logs to the database or publish a message to the message broker.

Request Body schema: application/json
timestamp
string <date-time>
required
Array of objects (Posting)
reference
string
object or null

Responses

Request samples

Content type
application/json
{
  • "reference": "ref:001",
  • "metadata": {
    },
  • "postings": [
    ],
  • "timestamp": "2000-01-23T04:56:07.000+00:00"
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get transaction from a ledger by its ID.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

txid
required
integer
Example: 1234

Transaction ID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Set the metadata of a transaction by its ID.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

txid
required
integer
Example: 1234

Transaction ID.

Request Body schema: application/json

metadata

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "admin": true,
  • "a": {
    }
}

Response samples

Content type
application/json
{
  • "error_code": "VALIDATION",
  • "error_message": "invalid transaction ID"
}

Revert a ledger transaction by its ID.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

txid
required
integer
Example: 1234

Transaction ID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create a new batch of transactions to a ledger.

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

Request Body schema: application/json
required
Array of objects (TransactionData)
Array
timestamp
string <date-time>
required
Array of objects (Posting)
reference
string
object or null

Responses

Request samples

Content type
application/json
{
  • "transactions": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

balances

Get the balances from a ledger's account

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

query Parameters
address
string
Example: address=users:001

Filter balances involving given account, either as source or destination.

after
string
Example: after=users:003

Pagination cursor, will return accounts after given address, in descending order.

pagination_token
string
Example: pagination_token=aHR0cHM6Ly9nLnBhZ2UvTmVrby1SYW1lbj9zaGFyZQ==

Parameter used in pagination requests. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results.

Responses

Response samples

Content type
application/json
{
  • "cursor": null
}

Get the aggregated balances from selected accounts

Authorizations:
basicAuth
path Parameters
ledger
required
string
Example: ledger001

Name of the ledger.

query Parameters
address
string
Example: address=users:001

Filter balances involving given account, either as source or destination.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}