{
  "openapi": "3.1.0",
  "info": {
    "title": "Satosh.si Inscriptions API",
    "version": "1.0.0",
    "description": "Create Bitcoin Ordinals inscriptions from your app: tickets, collectibles, certificates and more. Server-to-server only: keep your API key secret.",
    "termsOfService": "/developer-terms.html",
    "contact": { "email": "hello@satosh.si" }
  },
  "servers": [
    { "url": "https://satosh.si/v1", "description": "Bitcoin mainnet (live keys: ss_live_…)" },
    { "url": "https://test.satosh.si/v1", "description": "Testnet4 sandbox (test keys: ss_test_…)" }
  ],
  "security": [{ "apiKey": [] }],
  "paths": {
    "/signup": {
      "post": {
        "summary": "Create a developer account (sandbox: instant key; mainnet: request access)",
        "security": [],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "email", "acceptTerms"], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "website": { "type": "string" }, "acceptTerms": { "type": "boolean", "const": true } } } } } },
        "responses": { "201": { "description": "Account + API key (shown once)" }, "202": { "description": "Request pending approval (mainnet)" } }
      }
    },
    "/account": {
      "get": { "summary": "Your account, effective fee and recent webhook deliveries", "responses": { "200": { "description": "Account" } } }
    },
    "/account/webhook": {
      "put": {
        "summary": "Set (or clear) your webhook URL; returns the signing secret",
        "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": ["string", "null"], "description": "Public https URL" }, "rotateSecret": { "type": "boolean" } } } } } },
        "responses": { "200": { "description": "{ webhookUrl, webhookSecret }" } }
      }
    },
    "/fees": {
      "get": { "summary": "Current network fee rates (sat/vB)", "responses": { "200": { "description": "{ economy, normal, fast, minimum }" } } }
    },
    "/quote": {
      "post": {
        "summary": "Price an order without creating it",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["items"], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "feeRate": { "$ref": "#/components/schemas/FeeRate" } } } } } },
        "responses": { "200": { "description": "{ count, total, totalBtc, breakdown }" } }
      }
    },
    "/orders": {
      "post": {
        "summary": "Create an inscription order (1–20 items)",
        "parameters": [{ "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 200 }, "description": "Retries with the same key return the original order (200, Idempotent-Replayed: true) and use no quota." }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrder" } } } },
        "responses": { "201": { "description": "Order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      },
      "get": {
        "summary": "List your orders",
        "parameters": [
          { "name": "externalId", "in": "query", "schema": { "type": "string" }, "description": "Match order or item externalId" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100 } },
          { "name": "before", "in": "query", "schema": { "type": "string", "format": "date-time" } }
        ],
        "responses": { "200": { "description": "{ object: 'list', data: Order[] }" } }
      }
    },
    "/orders/{id}": {
      "get": { "summary": "Get an order", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "$ref": "#/components/responses/Error" } } }
    }
  },
  "components": {
    "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer ss_live_… / ss_test_…" } },
    "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } } } } } } } } },
    "schemas": {
      "FeeRate": { "oneOf": [{ "type": "number", "minimum": 1, "description": "sat/vB" }, { "type": "string", "enum": ["economy", "normal", "fast"] }], "default": "normal" },
      "Item": {
        "type": "object",
        "description": "One inscription. Provide text, data (base64) or a delegate. Max 380 KB per item.",
        "properties": {
          "text": { "type": "string", "description": "UTF-8 text (contentType defaults to text/plain;charset=utf-8)" },
          "data": { "type": "string", "contentEncoding": "base64" },
          "contentType": { "type": "string", "example": "image/webp" },
          "delegate": { "type": "string", "pattern": "^[0-9a-f]{64}i\\d+$", "description": "Show an existing inscription's content (e.g. shared event artwork). Makes each item tiny." },
          "metadata": { "type": "object", "description": "JSON stored on-chain as CBOR in the Ordinals metadata field (≤ 4 KB), e.g. ticket details" },
          "receiveAddress": { "type": "string", "description": "Taproot (bc1p…/tb1p…) address for this item; defaults to the order's" },
          "externalId": { "type": "string", "description": "Your ID for this item, e.g. a ticket ID" },
          "name": { "type": "string" }
        }
      },
      "CreateOrder": {
        "type": "object",
        "required": ["items"],
        "properties": {
          "items": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/Item" } },
          "receiveAddress": { "type": "string", "description": "Default Taproot address for items without their own" },
          "refundAddress": { "type": "string", "description": "Where overpayments and late payments are refunded (defaults to receiveAddress)" },
          "feeRate": { "$ref": "#/components/schemas/FeeRate" },
          "externalId": { "type": "string", "description": "Your ID for the whole order" }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "object": { "const": "inscription_order" },
          "status": { "type": "string", "enum": ["awaiting_payment", "underpaid", "broadcasting", "mempool", "confirmed", "expired"] },
          "externalId": { "type": ["string", "null"] },
          "network": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" },
          "expiresAt": { "type": "string", "format": "date-time" },
          "feeRate": { "type": "number" },
          "payment": { "type": "object", "properties": { "address": { "type": "string" }, "amount": { "type": "integer", "description": "sats" }, "amountBtc": { "type": "string" }, "paid": { "type": "integer" }, "bip21": { "type": "string" } } },
          "fees": { "type": "object", "properties": { "postage": { "type": "integer" }, "network": { "type": "integer" }, "service": { "type": "integer" }, "total": { "type": "integer" } } },
          "items": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "externalId": { "type": ["string", "null"] }, "receiveAddress": { "type": "string" }, "contentType": { "type": ["string", "null"] }, "size": { "type": "integer" }, "delegate": { "type": ["string", "null"] }, "metadata": { "type": ["object", "null"] }, "inscriptionId": { "type": ["string", "null"] }, "revealTxid": { "type": ["string", "null"] } } } },
          "change": { "type": "integer" },
          "refunds": { "type": "array", "items": { "type": "object" } },
          "error": { "type": ["string", "null"] }
        }
      }
    }
  },
  "webhooks": {
    "orderEvent": {
      "post": {
        "summary": "Order lifecycle event: order.created, order.underpaid, order.paid, order.broadcast, order.confirmed, order.expired, order.refunded",
        "description": "Signed with HMAC-SHA256: header Satoshsi-Signature: t=<unix>,v1=<hex hmac(secret, `${t}.${rawBody}`)>. Retried on non-2xx at 1m, 5m, 15m, 1h, 3h, 6h, 12h, 24h.",
        "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "created": { "type": "integer" }, "data": { "$ref": "#/components/schemas/Order" } } } } } },
        "responses": { "2XX": { "description": "Acknowledged" } }
      }
    }
  }
}
