Satosh.si API
Inscribe on Bitcoin from your app or site: tickets, collectibles, certificates, receipts. One HTTP call per batch of up to 20 inscriptions, signed webhooks as they move on-chain.
1. Get a key
2. Authenticate
Send your key as a bearer token. Keys start with ss_test_ (testnet sandbox at test.satosh.si) or ss_live_ (Bitcoin mainnet at satosh.si). Call the API only from your server. Never put a key in a browser or app bundle.
curl /v1/account -H "Authorization: Bearer $SATOSHSI_KEY"
3. Create an order
An order is a batch of 1–20 inscriptions with one payment. It returns a payment address and amount.
curl /v1/orders \
-H "Authorization: Bearer $SATOSHSI_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1234" \
-d '{
"receiveAddress": "",
"feeRate": "normal",
"externalId": "order-1234",
"items": [ { "text": "Hello, Bitcoin", "externalId": "item-1" } ]
}'
Node.js:
const res = await fetch('/v1/orders', {
method: 'POST',
headers: {
authorization: `Bearer ${process.env.SATOSHSI_KEY}`,
'content-type': 'application/json',
'idempotency-key': `order-${order.id}`,
},
body: JSON.stringify({ receiveAddress, feeRate: 'normal', items }),
});
const o = await res.json(); // o.payment.address, o.payment.amount (sats), o.payment.bip21
Response (abridged):
{ "id": "aB3…", "object": "inscription_order", "status": "awaiting_payment",
"payment": { "address": "…", "amount": 1273, "amountBtc": "0.00001273", "bip21": "bitcoin:…" },
"fees": { "postage": 546, "network": 181, "service": 546, "total": 1273 },
"items": [ { "index": 0, "externalId": "item-1", "inscriptionId": null, … } ],
"expiresAt": "…" }
Then poll GET /v1/orders/{id}, or better, use webhooks. Statuses: awaiting_payment → broadcasting → mempool → confirmed, or underpaid / expired. items[].inscriptionId is set once the inscription is broadcast.
4. Items
text | UTF-8 text (content type defaults to text/plain;charset=utf-8) |
data + contentType | Base64 file, e.g. image/webp. Max 380 KB per item. Keep images small: size is most of the price. |
delegate | An existing inscription ID (<txid>i0) whose content this inscription displays. Inscribe artwork once, reference it from many items cheaply. |
metadata | JSON object (≤ 4 KB), stored on-chain as CBOR in the standard Ordinals metadata field. |
receiveAddress | Taproot address for this item; defaults to the order's receiveAddress. |
externalId | Your ID for the item (e.g. ticket ID), searchable with GET /v1/orders?externalId=…. |
5. Example: event tickets
Inscribe the event artwork once (a normal item). Then each ticket is a ~150 vB inscription that delegates to the artwork and carries its own metadata, sent to each attendee's wallet (or yours, to transfer later):
{
"feeRate": "economy",
"externalId": "event-42-batch-1",
"items": [
{ "delegate": "<artwork txid>i0", "metadata": { "event": "Satosh.si Live", "date": "2026-12-31", "seat": "B1", "ticket": "T-0001" },
"receiveAddress": "…attendee1", "externalId": "T-0001" },
{ "delegate": "<artwork txid>i0", "metadata": { "event": "Satosh.si Live", "date": "2026-12-31", "seat": "B2", "ticket": "T-0002" },
"receiveAddress": "…attendee2", "externalId": "T-0002" }
]
}
Coming soon: collections (parent/child), so every ticket is verifiably part of one event on-chain, and prepaid credits, so orders are inscribed instantly without a per-order payment.
6. Payment
Each order has its own payment address. Pay payment.amount sats from any wallet (your treasury, or show payment.bip21 as a QR to your customer). Orders expire after . Overpayments come back as change; late or extra payments are refunded automatically to refundAddress (or receiveAddress). Fees: postage (546 sats per item, stays with the inscription), the Bitcoin network fee, and the Satosh.si service fee (; partner rates available).
7. Webhooks
Set a public https URL with PUT /v1/account/webhook {"url": "https://…"}. The response includes your signing secret (whsec_…). Events: order.created, order.underpaid, order.paid, order.broadcast, order.confirmed, order.expired, order.refunded. Each POST body is { id, type, created, data: Order }. Non-2xx responses are retried at 1m, 5m, 15m, 1h, 3h, 6h, 12h and 24h. Verify every delivery:
import { createHmac, timingSafeEqual } from 'node:crypto';
// rawBody must be the exact request body string
function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // replay window
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}
// header: req.headers['satoshsi-signature']. Dedupe by event id: deliveries can repeat.
8. Idempotency
Send an Idempotency-Key header with every POST /v1/orders. If the request is retried with the same key, you get the original order back (200 with Idempotent-Replayed: true) instead of a duplicate, and it doesn't count against your rate limit.
9. Errors & limits
Errors look like {"error": {"type": "invalid_request", "message": "…"}}. Types: invalid_request (400), authentication_error (401), permission_error (403), not_found (404), rate_limit (429, with Retry-After), service_unavailable (503, retry), internal_error (500). Default limits: 120 orders/hour per account (raise on request), 300 quotes/min, 600 requests/min.
Machine-readable spec: /v1/openapi.json. Questions: .