Note: The Libra Client API is currently under development and may be updated in the future.
The Libra client API is based on the JSON-RPC protocol. This specification defines the client API endpoints and types, and provides usage examples.
JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Refer to the JSON-RPC Specification for further details.
The JSON-RPC protocol allows requests to be batched. An arbitrary number of requests 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
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.
Description
Submit a signed transaction to a full node.
| Name | Type | Description |
| data | string | Signed transaction data - hex-encoded bytes of serialized Libra SignedTransaction type. |
Null - on success
Errors during the transaction are indicated by different error codes:
| -32000 | Default server error |
| -32001 | VM validation error |
| -32002 | VM verification error |
| -32003 | VM invariant violation error |
| -32004 | VM deserialization error |
| -32005 | VM execution error |
| -32006 | VM unknown error |
| -32007 | Mempool error: invalid sequence number |
| -32008 | Mempool is full error |
| -32009 | Mempool error: account reached max capacity per account |
| -32010 | Mempool error: invalid update (only gas price increase is allowed) |
| -32011 | Mempool error: transaction did not pass VM validation |
| -32012 | Unknown error |
More information might be available in the “message” field, but this is not guaranteed.
// Request: submits a transaction whose hex-encoded LCS byte representation is in params
curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"submit","params":["c1fda0ec67c1b87bfb9e883e2080e530040000000000000002f401a11ceb0b010007014600000002000000034800000011000000045900000004000000055d0000001c00000007790000004900000008c20000001000000009d200000022000000000000010001010100020203000003040101010006020602050a0200010501010405030a020a0205050a02030a020a020109000c4c696272614163636f756e74166372656174655f746573746e65745f6163636f756e74066578697374731d7061795f66726f6d5f73656e6465725f776974685f6d6574616461746100000000000000000000000000000000010105010e000a001101200305000508000a000b0138000a000a020b030b04380102010700000000000000000000000000000000034c425201540005034ac94d88e90acd4cf0294e898e421e9404106484f428e88bba93de5053e051acb6ec0180969800000000000400040040420f00000000000000000000000000034c42528c8dd15e000000000020500a9002995e1af93bbdaf977385ed507b174bb3dc6936efd72612d56198a19d4084766159c40c4e91e61e3dbc30a9553c3111a7a582981d57ce4dff0aa383a529209b15046850c5115ef16b0b2e0c861be71186effb1b5707495e12ca06fe660a"],"id": 1}'
// Response, for successful transaction submission
{
"id":1,
"jsonrpc": "2.0",
"result": null
}
Description
Get the transactions on the blockchain
| Name | Type | Description |
| start_version | u64 | Start on this transaction version for this query |
| limit | u64 | Limit the number of transactions returned |
| include_events | bool | Set to true, to also fetch events for each transaction |
Array of Transaction objects
if include_events is false, the events field in the Transaction object will be an empty array.
// Request: fetches 10 transactions since version 1000
curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"get_transactions","params":[4433485, 10, false],"id":1}'
// Response
{
"id":1,
"jsonrpc":"2.0",
"result":[
{
"events":[
],
"gas_used":0,
"transaction":{
"expiration_time":1590680747,
"gas_unit_price":0,
"max_gas_amount":1000000,
"public_key":"500a9002995e1af93bbdaf977385ed507b174bb3dc6936efd72612d56198a19d",
"script":{
"amount":10000000,
"auth_key_prefix":"6484f428e88bba93de5053e051acb6ec",
"metadata":"",
"metadata_signature":"",
"receiver":"4ac94d88e90acd4cf0294e898e421e94",
"type":"peer_to_peer_transaction"
},
"script_hash":"c8bc3dda60e9662965b3223c22e3d3e3e7b6f698cf1a6930a449eb99daa35e7c",
"sender":"c1fda0ec67c1b87bfb9e883e2080e530",
"sequence_number":0,
"signature":"fe335285e5d87db25f86041d033414bfdf77ddae6f0dfbdc65ff4f5965ff810ef9c85ce00ede0820ce0cf5903f9ab3e93fa6e49bbf770aba9b083a985361fa01",
"signature_scheme":"Scheme::Ed25519",
"type":"user"
},
"version":4433485,
"vm_status":4001
},
....
]
}
Description
Get the latest account state for a given account.
| Name | Type | Description |
| account | string | Hex-encoded account address. |
Account - If account exists
Null - If account does not exist
// Request: fetches account state for account address "0xc1fda0ec67c1b87bfb9e883e2080e530"
curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"get_account_state","params":["c1fda0ec67c1b87bfb9e883e2080e530"],"id":1}'
// Response
{
"id":1,
"jsonrpc":"2.0",
"result":{
"authentication_key":"bbdcca6b06aa596ca700cb23ba74cc8ec1fda0ec67c1b87bfb9e883e2080e530",
"balances":[
{
"amount":200000000,
"currency":"LBR"
}
],
"delegated_key_rotation_capability":false,
"delegated_withdrawal_capability":false,
"received_events_key":"0000000000000000c1fda0ec67c1b87bfb9e883e2080e530",
"sent_events_key":"0100000000000000c1fda0ec67c1b87bfb9e883e2080e530",
"sequence_number":1
}
}
// Sample Response for non-existent account
{
"id":1,
"jsonrpc": "2.0",
"result": null,
}
Description
Get the transaction sent by the account with the given sequence number
| Name | Type | Description |
| account | string | The account address, a hex-encoded string |
| sequence | u64 | The account sequence number |
| include_events | bool | Set to true to also fetch events generated by the transaction |
Transaction - If transaction exists
Null - If transaction does not exist
// Request: fetches transaction for account address "0xc1fda0ec67c1b87bfb9e883e2080e530" and sequence number 0, without including events associated with this transaction
curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"get_account_transaction","params":["c1fda0ec67c1b87bfb9e883e2080e530", 0, false],"id":1}'
// Response
{
"id":1,
"jsonrpc":"2.0",
"result":{
"events":[
],
"gas_used":0,
"transaction":{
"expiration_time":1590680747,
"gas_unit_price":0,
"max_gas_amount":1000000,
"public_key":"500a9002995e1af93bbdaf977385ed507b174bb3dc6936efd72612d56198a19d",
"script":{
"amount":10000000,
"auth_key_prefix":"6484f428e88bba93de5053e051acb6ec",
"metadata":"",
"metadata_signature":"",
"receiver":"4ac94d88e90acd4cf0294e898e421e94",
"type":"peer_to_peer_transaction"
},
"script_hash":"c8bc3dda60e9662965b3223c22e3d3e3e7b6f698cf1a6930a449eb99daa35e7c",
"sender":"c1fda0ec67c1b87bfb9e883e2080e530",
"sequence_number":0,
"signature":"fe335285e5d87db25f86041d033414bfdf77ddae6f0dfbdc65ff4f5965ff810ef9c85ce00ede0820ce0cf5903f9ab3e93fa6e49bbf770aba9b083a985361fa01",
"signature_scheme":"Scheme::Ed25519",
"type":"user"
},
"version":4433485,
"vm_status":4001
}
}
Description
Get the current blockchain metadata (e.g., current state of a Libra full node). All Read operations can be batched with get_metadata rpc to obtain synced metadata information with the request.
You can use this endpoint to verify liveness / status of nodes in the network:
get_metadata returns the latest transaction version and the block timestamp. If the timestamp or version is old (from the past), it means that the full node is not not up-to-date.
None
| Name | Type | Description |
| version | u64 | The latest transaction version |
| timestamp | u64 | The block timestamp |
// Request: fetches current block metadata
curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"get_metadata","params":[],"id":1}'
// Response
{
"id":1,
"jsonrpc": "2.0",
"result": {
"version": 100,
"timestamp": 1584055164079210,
}
}
Description
Fetch the events for a given event stream.
| Name | Type | Description |
| key | string | Globally unique identifier of an event stream.
Note: For sent and received events, a client can use get_account_state to get the event key of the event streams for a given user. |
| start | integer | For this query, start at the event with this sequence number |
| limit | integer | Maximum number of events retrieved |
Returns array of Event objects
//Request: get events associated with event stream key "0100000000000000c1fda0ec67c1b87bfb9e883e2080e530"
curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"get_events","params": ["0100000000000000c1fda0ec67c1b87bfb9e883e2080e530", 0, 10], "id":1}'
//Response
{
"id":1,
"jsonrpc":"2.0",
"result":[
{
"data":{
"amount":{
"amount":10000000,
"currency":"LBR"
},
"metadata":"",
"receiver":"4ac94d88e90acd4cf0294e898e421e94",
"type":"sentpayment"
},
"key":"0100000000000000c1fda0ec67c1b87bfb9e883e2080e530",
"sequence_number":0,
"transaction_version":4433485
},
{
"data":{
"amount":{
"amount":100000000,
"currency":"LBR"
},
"metadata":"",
"receiver":"4ac94d88e90acd4cf0294e898e421e94",
"type":"sentpayment"
},
"key":"0100000000000000c1fda0ec67c1b87bfb9e883e2080e530",
"sequence_number":1,
"transaction_version":10099706
}
]
}
Description
Get information about various currencies supported by the Libra blockchain
None
| Name | Type | Description |
| code | string | Currency Code |
| fractional_part | u64 | Max fractional part of single unit of currency allowed in a transaction |
| scaling_factor | u64 | Factor by which the amount is scaled before it is stored in the blockchain |
| mint_events_key | string | Unique key for the mint events stream of this currency |
| burn_events_key | string | Unique key for the burn events stream of this currency |
| preburn_events_key | string | Unique key for the preburn events stream of this currency |
| cancel_burn_events_key | string | Unique key for the cancel_burn events stream of this currency |
| exchange_rate_update_events_key | string | Unique key for the exchange rate update events stream of this currency |
// Request: fetches currencies supported by the system
curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"get_currencies","params":[],"id":1}'
// Response
{
"id": 1,
"jsonrpc": "2.0",
"result": [
{
"code": "LBR",
"fractional_part": 1000,
"scaling_factor": 1000000
}
...
]
}
Description
A Libra account.
| Name | Type | Description |
| sequence_number | u64 | The next sequence number for the current account |
| authentication_key | string | Hex-encoded authentication key for the account |
| delegated_key_rotation_capability | bool | If true, another account has the ability to rotate the authentication key for this account. |
| delegated_withdrawal_capability | bool | If true, another account has the ability to withdraw funds from this account. |
| balances | Array of Amount objects | Balances of all the currencies associated with an account |
| sent_events_key | string | Unique key for the sent events stream of this account |
| received_events_key | string | Unique key for the received events stream of this account |
| Name | Type | Description |
| amount | u64 | amount in currency microunits |
| currency | string | currency string identifier |
Description
A transaction on the blockchain.
| Name | Type | Description |
| version | u64 | The on-chain version or unique identifier of this transaction |
| events | Event | List of associated events. Empty for no events |
| transaction_data | Object | Metadata for this transaction. Possible types are BlockMetadataTransaction, WriteSetTransaction, UserTransaction, UnknownTransaction. You should use the "type" field to distinguish the type of the Object. (e.g., if "type" field is "user", this is a UserTransaction object) |
| vm_status | u64 | Status code representing the result of the VM processing this transaction. |
| gas_used | u64 | Amount of gas used by this transaction |
{
"version": 100,
"transaction_data": {
"type": "user"
"sender": "0xc94770007dda54cF92009BFF0dE90c06F603a09f",
"sequence_number": 0,
"max_gas_amount": 7000,
"gas_unit_price": 3,
"expiration_time": 1582007787665718,
},
"events": [] // empty because include_events is set to false
}
Description
A Libra network transaction that contains the metadata for the block. This transaction is always at the beginning of a block.
| Name | Type | Description |
| type | string | Const string “blockmetadata” |
| timestamp_usecs | u64 | Timestamp for the current block, in microseconds |
Description
A Libra network transaction that modifies storage data directly. Currently, no details are exposed in the API.
| Name | Type | Description |
| type | string | Const string “writeset” |
Description
User submitted transaction.
| Name | Type | Description |
| type | string | Const string “user” |
| sender | string | Hex-encoded account address of the sender |
| signature_scheme | string | Signature scheme used to sign this transaction |
| signature | string | Hex-encoded signature of this transaction |
| public_key | string | Hex-encoded public key of the transaction sender |
| sequence_number | u64 | Sequence number of this transaction corresponding to sender's account |
| max_gas_amount | u64 | Maximum amount of gas that can be spent for this transaction |
| gas_unit_price | u64 | Maximum gas price to be paid per unit of gas |
| expiration_time | u64 | The expiration time (Unix Epoch in seconds) for this transaction |
| script_hash | string | Hex-encoded hash of the script used in this transaction |
| script | Object | The transaction script and arguments of this transaction, represented as one of PeerToPeerScript, MintScript or UnknownScript. |
Description
Metadata for unsupported transaction types
| Name | Type | Description |
| type | string | Const string “unknown” |
Description
Transaction script for peer-to-peer transfer of resource
| Name | Type | Description |
| type | string | Const string “peer_to_peer_transaction” |
| receiver | Hex string | The receiver libra address |
| auth_key_prefix | Hex string | The auth_key_prefix |
| amount | u64 | The amount of microlibras being sent |
| metadata | Hex string | The metadata supplied |
Description
Transaction script for a special transaction used by the faucet to mint Libra and send to a user.
| Name | Type | Description |
| type | string | Const string “mint_transaction” |
| receiver | Hex string | The receiver libra address |
| auth_key_prefix | Hex string | The auth_key_prefix |
| amount | u64 | The amount of microlibras being sent |
Description
Currently unsupported transaction script
| Name | Type | Description |
| type | string | Const string “unknown_transaction” |
Description
An event emitted during a transaction
| Name | Type | Description |
| key | string | Gobally unique identifier of event stream |
| sequence_number | integer | Sequence number of the current event in the given even stream |
| transaction_version | integer | Version of the transaction that emitted this event |
| data | object | ReceivedPayment or SentPayment or UnknownEvent object |
Description
Event emitted when an account receives a payment.
| Name | Type | Description |
| type | string | Const string “receivedpayment” |
| amount | Amount | Amount received from the sender of the transaction |
| sender | Hex string | Hex-encoded address of the account whose balance was debited to perform this deposit. If the deposited funds came from a mint, the sender address will be 0x0...0. |
| receiver | Hex string | Hex-encoded address of the account whose balance was credited by this deposit. |
| metadata | Hex string | An optional field that can contain extra metadata for the event.
Note: This information can be used by an off-chain API to implement a sub-addressing scheme for a wallet. |
Description
Event emitted when an account sends a payment.
| Name | Type | Description |
| type | string | Const string “sentpayment” |
| amount | Amount | Amount transferred in a transaction |
| receiver | string | Hex-encoded address of the account whose balance was credited to by this withdrawal. If the withdrawn funds were burned, the received address will be 0x0...0. |
| sender | string | Hex-encoded address of the account whose balance was debited by this withdrawal. |
| metadata | string | An optional field that can contain extra metadata for the event.
Note: This information can be used by another API to implement a subaddressing scheme for a wallet |
Description
Represents events currently unsupported by JSON-RPC API.
| Name | Type | Description |
| type | string | Const string “unknown” |