Satellite
Testnet Only. Using mainnet coins will result in lost funds.
The Blockstream Satellite API is currently operating in Beta mode utilizing Lightning Testnet for payment.
Testnet Only. Using mainnet coins will result in lost funds.
The Blockstream Satellite API is currently operating in Beta mode utilizing Lightning Testnet for payment.
Satellite

API Documentation

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://satellite.blockstream.com/api.

You can open a payment channel directly at: 039d2201586141a3fff708067aa270aa4f6a724227d5740254d4e34da262a79c2a@35.247.76.117

POST /order

Place an order for a message transmission. The body of the POST must provide a file containing the message and a bid in millisatoshis. If the bid is below an allowed minimum millisatoshis per byte, an error is returned.

For example, 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
Copied!

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"}}
Copied!

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
Copied!

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.

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
Copied!

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
Copied!

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
Copied!

GET /orders/queued

Retrieve a list of paid, but unsent orders. Both pending orders and the order currently being transmitted are returned. Optionally, accepts a parameter specifying how many queued order to return.

curl $SATELLITE_API/orders/queued
Copied!


curl $SATELLITE_API/orders/queued?limit=18
Copied!

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.

GET /orders/sent

Retrieves a list of up to 20 sent orders in reverse chronological order. Optionally, accepts the parameter before (a timestamp in ISO 8601 format) specifying that only orders before the given time are to be returned.

curl $SATELLITE_API/orders/sent
Copied!


curl $SATELLITE_API/orders/sent?limit=18
Copied!

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.

GET /info

Returns information about the c-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"}
Copied!

GET /subscribe/:channels

Subscribe to one or more server-side 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
Copied!

Example Applications

Example Applications

Example Python applications are available at the Blockstream 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.