The Libra client API is based on the JSON-RPC protocol. This specification defines the client API endpoints and types, and provides usage examples.
List of released stable methods (unless specifically mentioned, all parameters are required for the method.):
- submit(data: string) -> void
- get_transactions(start_version: unsigned_int64, limit: unsigned_int64, include_events: boolean) -> List<Transaction>
- get_account(account: string) -> Account
- get_account_transaction(account: string, sequence_number: unsigned_int64, include_events: boolean) -> List<Transaction>
- get_account_transactions(account: string, start: unsigned_int64, limit: unsigned_int64, include_events: boolean) -> Transaction
- get_metadata(version: unsigned_int64) -> Metadata
- get_events(key: string, start: unsigned_int64, limit: unsigned_int64) -> List<Event>
- get_currencies() -> List<CurrencyInfo>
For implementing a client, please checkout our Client Implementation Guide
JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Refer to the JSON-RPC Specification for further details.
JSON-RPC response object is extended with the following fields:
| field | type | meaning |
|---|---|---|
| libra_chain_id | unsigned int8 | network chain id, e.g. testnet chain id is 2 |
| libra_ledger_version | unsigned int64 | server side latest ledger version number |
| libra_ledger_timestampusec | unsigned int64 | server side latest ledger timestamp microseconds |
You can use these information to verify liveness / status of nodes in the network: if the timestamp or version is old (from the past), it means that the request hit a full node that is not up-to-date.
{
"id": 1,
"jsonrpc": "2.0",
"libra_chain_id": 2,
"libra_ledger_timestampusec": 1596680521771648,
"libra_ledger_version": 3253133,
"result": {
"timestamp": 1596680521771648,
"version": 3253133
}
}
The JSON-RPC protocol allows requests to be batched. An arbitrary number of requests (max 20 by default) can be combined into a single batch and submitted to the server. These requests will be processed together under a single request context.
If errors occur during a request, they are returned in an error object, as defined in: https://www.jsonrpc.org/specification#error_object For any invalid request or parameters request, standard Error code and message with human readable information will be returned.
| code | meaning |
|---|---|
| -32600 | standard invalid request error |
| -32601 | method not found or not specified |
| -32602 | invalid params |
| -32604 | invalid format |
Unless specifically mentioned below, Libra JSON-RPC will return the default error code - 32000 for generic server-side errors. More information may be returned in the ‘message’ and the ‘data’ fields, but this is not guaranteed.
We use URI versioning to version our API, current version is v1. For example, to hit testnet, the server url is: https://client.testnet.libra.org/v1. You may check API-CHANGELOG.md and learn more about our API changes.