Developer documentation

streamd-apis

WebSocket and JSON-RPC APIs

If you want to communicate directly with the streamd server, you can use the WebSocke…

API Changes

The WebSocket and JSON-RPC APIs are still under development and subject to change.

STREAMD

streamd-apis

STREAMDWEBSOCKET AND JSON-RPC APIAPI changesConnect streamdReason for running persona…

STREAMD

The core peer-to-peer server that runs the Stream network is called streamd. Each str…

WebSocket and JSON-RPC APIs

To communicate directly with a streamd server, use the WebSocket API or JSON-RPC API.…

API Changes

WebSocket and JSON-RPC APIs are still under development and are subject to change.

Request Format

Both the WebSocket API and JSON-RPC use JSON for requests and responses. Methods and …

Response Format

Successful response example { "id": 2, "status": "success", "type": "response", "resu…

Connecting to streamd

Before sending any commands to a streamd server, you need to know which server to con…

Why Run Your Own streamd Server?

There are many reasons to run your own streamd server. In general, you can trust your…

WebSocket API

JSON-RPC

You can use any HTTP client (such as Poster for Firefox or Postman for Chrome) submit…

Command-Line Interface

Command line and JSON-RPC connect to the same service, so the public server and serve…

WebSocket API

If you are trying something on the Stream ledger, you can skip writing your own WebSo…

Error Responses

It is almost impossible to enumerate all the ways in which errors can occur. Some may…

Caution When Sharing Errors

When your request results in an error, the entire request is logged in the background…

Universal Errors

All methods may return the following error code values: unknownCmd - The request does…

Format Conventions

WebSocket and JSON-RPC APIs generally take the same parameters, albeit in different w…

Unique Identifiers

Different types of objects can be identified in different ways: Accounts can be ident…

Specifying a Ledger

Many API methods require you to specify a ledger instance that includes the correct d…

Specifying Currency Amounts

Specifying Time

Possible Server States

Markers and Pagination

Modifying the Ledger

All changes to Stream’s global shared ledger are the result of transactions. The only…

API Methods

WebSocket and JSON-RPC API methods are defined based on command names and are divided…

Public Commands

account_currencies - Get the list of currencies that the account can send or receive …

Administrative Commands

The streamd management command is only available when connecting on a host and port i…

Command-Line Access

You can use the streamd application (as a standalone instance) as a JSON-RPC client. …

Account Information

The "accounts" in the Stream ledger represent STM holders and transaction senders. Ac…

account_info

The account_info command will retrieve information about the account, its activity an…

account_lines

The account_lines method returns information about the account's trust lines, includi…

account_offers

The account_offers method retrieves a list of offers by a specific account as a speci…

account_tx

The account_tx method retrieves a list of transactions involving the specified accoun…

wallet_propose

Use the wallet_propose method to generate the keys required for the new account. Acco…

Basic Data Types

Different types of objects are uniquely identified in different ways: Accounts are di…

Addresses

Each account in the Stream ledger is identified by an address in base58 encoding form…

Hashes

In Stream, especially the transactions and ledgers, they are uniquely determined by a…

Account Sequence Numbers

A serial number is a 32-bit unsigned integer that identifies a transaction or offer r…

Ledger Index

The ledger index is a 32-bit unsigned integer used to identify the ledger. The ledger…

Specifying a Ledger

Many API methods require you to specify a ledger instance that includes the correct d…

Currencies

There are two different currencies in Stream: stm and others. There are many differen…

Specifying Currency Amounts

Some API methods require you to specify a monetary amount. The specified style depend…

Currency Codes

There are two currency codes in the STM ledger:Three-character currency codes. Upperc…

Specifying Time

streamdThe server and its API represent times as unsigned integers. Measured as the n…

Possible Server States

Depending on how the streamd server is configured, running time, and other factors, a…

account_currencies

The account_currencies command retrieves a list of currencies that an account can sen…

account_channels

(need to enable PayChan amendment) The account_channels method returns information ab…

Ledger Information

Each streamd server maintains a complete copy of the current state of the STM ledger,…

ledger

Retrieve information about the public ledger. Example of request format: { "id": 14, …

ledger_closed

The ledger_closed method returns the unique identifier of the most recently closed le…

ledger_current

The ledger_current method returns the unique identifier of the currently ongoing ledg…

ledger_data

The ledger_data method retrieves the contents of the specified ledger. You can loop t…

ledger_entry

The ledger_entry method returns a single ledger object from the STM ledger in raw for…

ledger_request

The ledger_request command tells the server to obtain a specific ledger version from …

ledger_accept

The ledger_accept method forces the server to close the current working ledger and mo…

Transaction Management

Transactions are the only way to modify the shared state of the STM ledger. All activ…

tx

The tx method retrieves information for a single transaction. Example of request form…

transaction_entry

The transaction_entry method retrieves information for a single transaction from a sp…

tx_history

The tx_history method retrieves some recent transactions. Warning: This method is dep…

path_find

WebSocket API only! The path_find method finds possible payment paths and sends perio…

path_find: Create

The create subcommand path_find creates a persistent request to find possible paths t…

path_find: Close

path_find subcommand close instructs the server to stop sending information about cur…

path_find: Status

Requests an immediate update of the path_find subcommand status for the client's curr…

sign

sign method takes a transaction and key in JSON format and returns a signed binary re…

Auto-Filled Fields

If you omit them, the server will automatically try to autofill certain fields in tx_…

vstream_path_find

The vstream_path_find method is a simplified version of path_find that can be used ou…

submit

The submit method applies the transaction and sends it to the network for confirmatio…

Submit-Only Mode

The submission request contains the following parameters:FieldTypeDescriptiontx_blobS…

Sign-and-Submit Mode

This mode signs the transaction and commits it immediately. This mode is intended for…

book_offers

The book_offers method retrieves a list of quotes between two currencies, also known …

Subscriptions

When using subscriptions, you can have the server push updates to the client when var…

subscribe

The subscribe method requests the server to send periodic notifications when certain …

Ledger Stream

The ledger flow only sends ledgerClosed messages when the consensus process declares …

Transaction Streams

Many subscriptions result in messages about transactions, including the following:The…

Peer Status Stream

The administrator-only peer_status stream reports a wealth of information about strea…

unsubscribe

The unsubscribe command tells the server to stop sending messages for a specific subs…

Server Information

There are also commands that can retrieve information about the current status of the…

server_info

The server_info command requests a human-readable version of various information from…

server_state

The server_state command asks the server for various machine-readable information abo…

can_delete

With the online_delete and advisory_delete configuration options enabled, the can_del…

consensus_info

The consensus_info command provides information about the consensus process for debug…

fetch_info

The fetch_info command returns information about the objects this server is currently…

feature

The feature command returns information about the modifications that the server is aw…

get_counts

The get_counts command provides various statistics about the health of the server, ma…

ledger_cleaner

The ledger_cleaner command controls the Ledger Cleaner, an asynchronous maintenance p…

log_level

The log_level command changes the logging verbosity of the streamd server, or returns…

logrotate

The logrotate command closes and reopens the log file. This is intended to aid log ro…

validation_create

Use the validation_create command to generate the Streamd validator key. Similar to t…

validation_seed

The validation_seed command temporarily sets the secret value used by streamd for sig…

peers

The peers command returns streamd a list of all other servers currently connected to …

print

The print command returns the current status of various internal subsystems, includin…

Utility Methods

streamdThe server also provides some commands purely for convenience.

ping

The ping command returns a confirmation so that clients can test connection status an…

random

The random command provides a random number that is used as a source of entropy for c…

json

The json method is a proxy for running other commands and accepts the parameters of t…

connect

The connect command forces the streamd server to connect to a specific peer streamd s…

stop

Gracefully shut down the server. This stop request is an administrative command that …

novstream_check

The novstream_check command provides a quick way to check the status of an account's …