EXTERNAL INSCRIPTION API

Quote. Pay. Confirm.

Clients submit inscription files and options to the quote endpoint. The API locks the quote, returns the exact BTC payment amount, then verifies the payment transaction through Bitcoin Core before the inscription moves to fulfillment.

Flow

The service fee is decided by the API key sent with the quote request.

Pricing

No API key adds 3000 sats per inscription. Bronze keys add 2000 sats, Silver keys add 1000 sats, and Gold keys add 0 sats. Network fees are estimated from the submitted sat/vB fee rate and added with postage and padding.

Payment

Pay the exact quote.payment.amount_sats to quote.payment.payment_address. After broadcast, call POST /v1/inscriptions/payments with the quote id and payment txid.

Create Quote

Send files as base64 inside items. Include X-API-Key only when the customer has paid access.

curl -sS -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  --data '{
    "fee_rate_sat_vb": "2.5",
    "destination": "bc1p...",
    "postage_sats": 330,
    "padding_sats": 0,
    "items": [
      {
        "kind": "file",
        "name": "art.png",
        "content_type": "image/png",
        "content_base64": "iVBORw0KGgo..."
      }
    ]
  }' \
  "https://api.spamthechain.com/v1/inscriptions/quote"
{
  "quote": {
    "id": "inq_...",
    "tier": "silver",
    "pricing": {
      "service_fee_sats_per_inscription": 1000,
      "estimated_network_fee_sats": 1250,
      "postage_sats": 330,
      "total_sats": 2580,
      "total_btc": "0.0000258"
    },
    "payment": {
      "payment_address": "bc1qgm6zfscusf064ss330v7hywu6ap8l0h66evte0",
      "amount_sats": 2580,
      "amount_btc": "0.0000258",
      "min_confirmations": 1
    }
  }
}

Confirm Payment

The API creates the fulfillment request from the locked quote after it sees the payment tx.

curl -sS -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "quote_id": "inq_...",
    "txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
    "contact": "[email protected]"
  }' \
  "https://api.spamthechain.com/v1/inscriptions/payments"
{
  "request": {
    "id": "ins_...",
    "quote_id": "inq_...",
    "status": "paid",
    "payment": {
      "claimed_txid": "4a5e...",
      "confirmed_amount_btc": "0.0000258"
    }
  },
  "next_action": "ready_for_inscription"
}
curl -sS \
  "https://api.spamthechain.com/v1/inscriptions/requests/ins_..."

Batch Inscriptions

Use one quote for multiple files. The service fee is multiplied by item count.

{
  "fee_rate_sat_vb": "3",
  "batch_mode": "separate-outputs",
  "items": [
    {
      "kind": "file",
      "name": "one.html",
      "content_type": "text/html;charset=utf-8",
      "content_base64": "PGh0bWw+..."
    },
    {
      "kind": "text",
      "name": "note.txt",
      "text": "gm",
      "destination": "bc1p..."
    }
  ]
}