| Symptom | First action | Planning use |
|---|---|---|
| BID_TOO_SMALL (102) error on submit | Raise the bid until it is at least 1 msat per byte of message | Work out the bid from the message size before you send, not after the rejection |
| Total bid refused | Make the total bid more than the 1000 msat floor | Very short messages still need the minimum total |
| MESSAGE_FILE_TOO_SMALL (117) or MESSAGE_FILE_TOO_LARGE (118) | Check the file you attached and resize it | Treat these codes as the signal that the size is outside what the server accepts |
| Order sits in the queue after payment | Bump the bid on the queued order | A higher bid is the lever you control while waiting |
| Paid and sent, but nothing arrives at your receiver | Check the order state, then the receiver’s listener | Reception is not guaranteed for every receiver |
Bid minimums and error codes come from the Blockstream Satellite documentation and the satellite-api repository.
The Blockstream Satellite API lets you broadcast a text or file message globally: submit an order with a bid in millisatoshis, pay the returned Lightning invoice, then watch the order move from queued to transmitted. Payment is the only requirement.
This walkthrough belongs to our wider crypto satellite coverage. If you are weighing what the service costs overall, read about the blockstream satellite cost first, then return here to send your first message.
What you need before you start
You need an HTTP client, a way to pay a Lightning invoice and a message to send. Blockstream describes the service as an easy-to-use RESTful API for building applications that broadcast messages globally, and says the only criterion for using it is that the data is paid for.
Behind the scenes, the satellite-api project is a Lightning app built on c-lightning. It accepts messages for broadcast over Blockstream Satellite and takes payment over the Bitcoin Lightning Network. Your wallet therefore has to be able to pay a Lightning invoice, and that is the whole account setup.
- Sender side: any tool that can issue REST calls works, whether that is curl, a Python script or the command-line sender application in the Blockstream Satellite documentation.
- Payment side: a Lightning wallet that can pay an invoice by pasted invoice number or by QR code.
- Receiving side (optional): a satellite receiver is only needed if you want to see the message arrive yourself.
Sending the message
You send a message by posting an order that carries a bid and the message itself. The Blockstream Satellite documentation describes the process as starting with a sender application that requests transmission of a particular file or text message, after which the order is queued in the API server.
- Compose the text or choose the file you want to broadcast.
- Send a POST request to the /order endpoint. The repository documentation says the body must provide a bid in millisatoshis and a message.
- Read the response. It includes the JSON Lightning invoice and an auth token, so store both.
- Pay the invoice with your Lightning wallet.
- Poll the order state until it shows the message as received.
In Python, the same flow needs only an HTTP client to make the POST, then a call to your wallet or node to pay the invoice that comes back. Keep the bid in a variable, because you will want to adjust it if the server rejects it or the order stalls.
Using the command-line sender instead
If you would rather not hand-build requests, the documented command-line application asks for the bid in millisatoshi (msat) and suggests the minimum acceptable bid. Accept the suggestion for a first test, then raise it only if you need the message to move up the queue.
Setting the bid and understanding size limits
The fee is the bid you choose, quoted in millisatoshis for the whole message. The documentation sets two floors: the total bid must be at least 1000 msat, and the bid must work out to at least 1 msat per byte.
In practice, a short note is held up by the total floor, while a larger file is governed by the per-byte rate. Whichever floor is higher for your message is the one to plan around, and the bid you choose is a floor-or-above value, not a quote that gets rounded to it.
Symptom: the server returns BID_TOO_SMALL
Per the satellite-api repository, a bid below the allowed minimum per byte returns a BID_TOO_SMALL (102) error. Resubmit with a higher bid and nothing else changed.
Symptom: the file is rejected for its size
The repository lists MESSAGE_FILE_TOO_SMALL (117) and MESSAGE_FILE_TOO_LARGE (118) among its error codes, and MESSAGE_MISSING when no message is supplied. Those codes are the authoritative size check, so read the error in the response rather than guessing a limit. Fix the attachment, resend the order and keep the bid at or above the floors above.
Symptom: the order is paid but slow
You can increase the bid for an order that is sitting in the transmission queue through the /order/:uuid/bump endpoint. Use it when speed matters more than the original bid, and keep the UUID from your first response so the call targets the right order.
Paying the Lightning invoice
A message is transmitted only after its Lightning invoice is paid. The documentation tells you to take the Lightning invoice number printed on the console, or its QR code, and pay it using Bitcoin Lightning. If you are calling the API directly, the invoice is in the JSON response from your POST.
The invoice carries metadata that lets you check you are paying for the right thing: the repository notes that it includes the SHA256 digest of the uploaded message file and a UUID for the order. Compare that identifier with the one you stored before you confirm the payment in your wallet.
Once the payment is confirmed, the documentation says transmission starts as soon as the transmission queue serves your message. Confirmation does not mean instant transmission, so a short wait is normal.
Following the message from queued to received
Your order moves through a queue, a payment step, transmission and reception. It is queued in the API server first, becomes eligible for transmission after payment, and is finally transmitted. The state you can query at the end is received, which the repository defines as orders completely transmitted and received in all targeted regions.
- List by state: GET /orders/:state retrieves up to 20 orders in the state you name, so use it to check where your order sits.
- Fetch a transmitted message: GET /message/:seq_num retrieves a transmitted message by its unique sequence number.
- Cancel: to cancel an order, issue an HTTP DELETE request to /order/:uuid. Do this if you spot a mistake before transmission.
Stop and cancel rather than bump when the message content is wrong, since a higher bid only speeds a message you no longer want to send.
Seeing the message arrive on a satellite receiver
To watch your message come down from the satellite, run the listener on a machine connected to a Satellite receiver. The documentation gives the command as blocksat-cli api listen, and the listener saves the final result into the download directory, which defaults to ~/.blocksat/api/downloads/.
Do not treat a missing file as proof the order failed. The documentation states that API messages sent over satellite are not guaranteed to be received by all satellite receivers, and reception quality varies with location and weather. Check the order state through the API first; if it shows received but your receiver has nothing, the issue is on the reception side.
If you do not yet have a receiver, how to build a crypto satellite covers the hardware and setup side.
Frequently asked questions
| Question | Answer |
|---|---|
| Do I need a receiver to send a message? | No. Sending only requires that the data is paid for. A receiver is needed only if you want to listen for the broadcast yourself. |
| Can I change the bid after submitting? | Yes, while the order is still in the transmission queue. The bump endpoint increases its bid. |
| Can I use Python rather than curl? | Yes. The service is a RESTful API, so any client that can send the POST and read the JSON invoice works. |
| Which payment method does the service take? | Payments are made through Bitcoin Lightning, using the invoice returned when you create the order. |
