API Documentation
REST API
Each call to an API endpoint responds with a JSON object, whether the call is successful or results in an error.
The code samples below assume that you've set SATELLITE_API in your shell to: https://api.blockstream.space
You can open a payment channel directly at: 03f21fc2e8ab0540eeb74dd715b5b66638ec1cd392db00009b320b3ed8c409bd57@35.197.62.113
POST /order
Place an order for a message transmission. The body of the POST must provide a bid in millisatoshis and a message, provided either as a
message parameter string or as an HTTP form-based file upload. If the bid is below an allowed minimum millisatoshis per byte, a
BID_TOO_SMALL (102) error is returned.
For example, to place an order to transmit the message "Hello world" with an initial bid of 10,000 millisatoshi, issue an HTTP POST request like this:
curl -F "bid=10000" -F "message=Hello World" $SATELLITE_API/order
Or, to place an order to transmit the file hello_world.png with an initial bid of 10,000 millisatoshi, issue an HTTP POST request like this:
curl -F "bid=10000" -F "file=@/path/to/upload/file/hello_world.png" $SATELLITE_API/order
If successful, the response includes the JSON Lightning invoice as returned by Lightning Charge's POST /invoice and an authentication token that can be used to modify the order. Within the metadata of the Lightning invoice, metadata is included providing: the bid (in millisatoshis), the SHA256 digest of the uploaded message file, and a UUID for the order.
{"auth_token":"d784e322dad7ec2671086ce3ad94e05108f2501180d8228577fbec4115774750","uuid":"409348bc-6af0-4999-b715-4136753979df","lightning_invoice":{"id":"N0LOTYc9j0gWtQVjVW7pK","msatoshi":"514200","description":"BSS
Test","rhash":"5e5c9d111bc76ce4bf9b211f12ca2d9b66b81ae9839b4e530b16cedbef653a3a","payreq":"lntb5142n1pd78922pp5tewf6ygmcakwf0umyy039j3dndntsxhfswd5u5ctzm8dhmm98gaqdqdgff4xgz5v4ehgxqzjccqp286gfgrcpvzl04sdg2f9sany7ptc5aracnd6kvr2nr0e0x5ajpmfhsjkqzw679ytqgnt6w4490jjrgcvuemz790salqyz9far68cpqtgq3q23el","expires_at":1541642146,"created_at":1541641546,"metadata":{"sha256_message_digest":"0e2bddf3bba1893b5eef660295ef12d6fc72870da539c328cf24e9e6dbb00f00","uuid":"409348bc-6af0-4999-b715-4136753979df"},"status":"unpaid"}}
Error codes that can be returned by this endpoint include: BID_TOO_SMALL (102), FILE_MISSING (103),
MESSAGE_FILENAME_MISSING (116), MESSAGE_FILE_TOO_SMALL (117), MESSAGE_FILE_TOO_LARGE (118),
BID_TOO_SMALL (102), MESSAGE_TOO_LONG (125), MESSAGE_MISSING (126).
POST /order/:uuid/bump
Increase the bid for an order sitting in the transmission queue. The bid_increase must be provided in the body of the POST. A Lightning invoice is returned for it and, when it is
paid, the increase is added to the current bid. An auth_token must also be provided. For example, to increase the bid on the order placed above by 100,000 millisatoshis, issue a POST
like this:
curl -v -F "bid_increase=100000" -F "auth_token=d784e322dad7ec2671086ce3ad94e05108f2501180d8228577fbec4115774750" $SATELLITE_API/order/409348bc-6af0-4999-b715-4136753979df/bump
Response object is in the same format as for POST /order.
As shown below for DELETE, the auth_token may alternatively be provided using the X-Auth-Token HTTP header.
Error codes that can be returned by this endpoint include: INVALID_AUTH_TOKEN (109), ORDER_NOT_FOUND (104),
BID_INCREASE_MISSING (105), ORDER_BUMP_ERROR (119).
GET /order/:uuid
Retrieve an order by UUID. Must provide the corresponding auth token to prove that it is yours.
curl -v -H "X-Auth-Token: 5248b13a722cd9b2e17ed3a2da8f7ac6bd9a8fe7130357615e074596e3d5872f" $SATELLITE_API/order/409348bc-6af0-4999-b715-4136753979df
Error codes that can be returned by this endpoint include: INVALID_AUTH_TOKEN (109), ORDER_NOT_FOUND (104).
DELETE /order/:uuid
To cancel an order, issue an HTTP DELETE request to the API endpoint /order/:uuid/ providing the UUID of the order. An auth_token must also be
provided. For example, to cancel the order above, issue a request like this:
curl -v -X DELETE -F "auth_token=5248b13a722cd9b2e17ed3a2da8f7ac6bd9a8fe7130357615e074596e3d5872f" $SATELLITE_API/order/409348bc-6af0-4999-b715-4136753979df
The auth_token may be provided as a parameter in the DELETE body as above or may be provided using the X-Auth-Token HTTP header, like this:
curl -v -X DELETE -H "X-Auth-Token: 5248b13a722cd9b2e17ed3a2da8f7ac6bd9a8fe7130357615e074596e3d5872f" $SATELLITE_API/order/409348bc-6af0-4999-b715-4136753979df
Error codes that can be returned by this endpoint include: INVALID_AUTH_TOKEN (109), ORDER_NOT_FOUND (104),
ORDER_CANCELLATION_ERROR (120).
GET /orders/pending
Retrieve a list of 20 orders awaiting payment ordered by creation time. For pagination, optionally specify a before parameter (in ISO 8601 format) that specifies that the 20 orders
immediately prior to the given time be returned.
curl $SATELLITE_API/orders/pending
curl $SATELLITE_API/orders/pending?before=2019-01-16T18:13:46-08:00
The response is a JSON array of records (one for each queued message). The revealed fields for each record include: uuid, bid,
bid_per_byte, message_size, message_digest, status,
created_at, started_transmission_at, and ended_transmission_at.
Error codes that can be returned by this endpoint include: INVALID_DATE (113).
GET /orders/queued
Retrieve a list of paid, but unsent orders in descending order of bid-per-byte. Both pending orders and the order currently being transmitted are returned. Optionally, accepts a parameter specifying how many queued orders to return.
curl $SATELLITE_API/orders/queued
curl $SATELLITE_API/orders/queued?limit=18
The response is a JSON array of records (one for each queued message). The revealed fields for each record include: uuid, bid,
bid_per_byte, message_size, message_digest, status,
created_at, started_transmission_at, and ended_transmission_at.
Error codes that can be returned by this endpoint include: LIMIT_TOO_LARGE (101).
GET /orders/sent
Retrieves a list of up to 20 sent orders in reverse chronological order. For pagination, optionally specify a before parameter (in ISO 8601 format) that specifies that the 20 orders
immediately prior to the given time be returned.
curl $SATELLITE_API/orders/sent
curl $SATELLITE_API/orders/sent?before=2019-01-16T18:13:46-08:00
The response is a JSON array of records (one for each queued message). The revealed fields for each record include: uuid, bid,
bid_per_byte, message_size, message_digest, status,
created_at, started_transmission_at, and ended_transmission_at.
Error codes that can be returned by this endpoint include: INVALID_DATE (113).
GET /info
Returns information about the Core Lightning node where satellite API payments are terminated. The response is a JSON object consisting of the node ID, port, IP addresses, and other information useful for opening payment channels. For example:
{"id":"032c6ba19a2141c5fee6ac8b6ff6cf24456fd4e8e206716a39af3300876c3a4835","port":42259,"address":[],"version":"v0.5.2-2016-11-21-1937-ge97ee3d","blockheight":434,"network":"regtest"}
GET /subscribe/:channels
Subscribe to one or more server-sent events channels. The channels parameter is a comma-separated list of event channels. Currently, only one channel is available:
transmissions, to which an event is pushed each time a message transmission begins and ends. Event data includes a JSON representation of the order, including its current status.
curl $SATELLITE_API/subscribe/:channels
Error codes that can be returned by this endpoint include: CHANNELS_EQUALITY (124).
Example Applications
Example Python applications are available at the Capitalblockstream Satellite examples directory as a reference regarding how to implement the interaction with the API. There is one application specifically for sending data to the API, called "API data sender", and another application for reading the API data acquired by the Blockstream Satellite receiver, called "API data reader". Additionally, there is one application that allows testing API data reception directly through the internet, without the actual satellite receiver hardware, called "demo receiver". Refer to the documentation in the given link.
Developer Version
The Developer version (for testing purposes) of Satellite API utilizes Lightning Testnet for payment. In order to use the Developer Version, you need to set SATELLITE_API in your
shell to: https://api.blockstream.space/testnet
There is a simple view of queued, pending, and sent messages for all transmissions using the Developer Version at: https://api.blockstream.space/testnet/queue.html
To make testnet payments using the developer version, you can open a payment channel directly at:
039d2201586141a3fff708067aa270aa4f6a724227d5740254d4e34da262a79c2a@34.83.166.97
Please note that using mainnet coins on the developer version will result in lost funds.