{"info":{"description":"swornly is a substrate of small, deterministic tools that AI agents pay for\nper call, each returning an HMAC-signed receipt. The first tool renders\nMarkdown to a styled PDF; the rest are verification oracles (below). Each\ncall is gated by one of two payment rails:\n\n  * `POST /convert`      \u2014 x402 (USDC on Base, Coinbase facilitator).\n  * `POST /convert/l402` \u2014 L402 (Lightning sats, macaroon + BOLT-11).\n\nFlow for x402:\n  1. POST /convert with `{ \"markdown\": \"...\" }`.\n  2. Receive 402 with the `accepts` array of payment requirements.\n  3. Sign EIP-3009 `transferWithAuthorization` and resubmit with the\n     `X-PAYMENT` header set to the base64-encoded payment payload.\n  4. Response is `application/pdf` plus `X-PAYMENT-RESPONSE`.\n\nFlow for L402:\n  1. POST /convert/l402 with `{ \"markdown\": \"...\" }`.\n  2. Receive 402 with `WWW-Authenticate: L402 macaroon=\"...\", invoice=\"...\"`\n     and a JSON body containing `{macaroon, invoice, amount_sats,\n     payment_hash, expires_at}`.\n  3. Pay the BOLT-11 invoice on Lightning. Obtain the payment preimage.\n  4. Resubmit with `Authorization: L402 <macaroon_b64>:<preimage_hex>`\n     and receive the PDF.\n\nDeterministic verification oracles (same two rails; JSON in, JSON out, each\nresponse carries an HMAC-signed `receipt`):\n\n  * `POST /dry-run/command`        \u2014 classify a shell/git command as\n    destructive + its blast radius BEFORE the agent runs it.\n  * `POST /diff/mcp-schema`        \u2014 diff two MCP `tools/list` payloads into\n    breaking vs non-breaking changes.\n  * `POST /snapshot/tool-contract` \u2014 stable fingerprint of a `tools/list`\n    for contract pinning / rug-pull detection.\n  * `POST /receipts/verify`        \u2014 free: re-verify any receipt.\n\nEach oracle has an `/l402` sibling (e.g. `POST /dry-run/command/l402`) that\ntakes the Lightning rail instead of x402.\n","title":"swornly \u2014 deterministic pay-per-call tools for agents (x402 + L402)","version":"1.2.0"},"openapi":"3.1.0","paths":{"/convert":{"post":{"operationId":"convertMarkdownToPdf","parameters":[{"description":"Base64-encoded x402 payment payload.","in":"header","name":"X-PAYMENT","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"markdown":{"description":"Raw Markdown source to render.","type":"string"}},"required":["markdown"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/pdf":{"schema":{"format":"binary","type":"string"}}},"description":"PDF file","headers":{"X-PAYMENT-RESPONSE":{"description":"Base64-encoded settlement receipt from the facilitator.","schema":{"type":"string"}}}},"400":{"description":"Bad request (missing/invalid markdown)"},"402":{"content":{"application/json":{"schema":{"properties":{"accepts":{"items":{"type":"object"},"type":"array"},"error":{"type":"string"},"x402Version":{"type":"integer"}},"type":"object"}}},"description":"Payment required (x402)"}},"summary":"Convert Markdown to PDF (x402-gated)"}},"/convert/l402":{"post":{"operationId":"convertMarkdownToPdfL402","parameters":[{"description":"L402 credentials \u2014 `L402 <macaroon_b64>:<preimage_hex>`.","in":"header","name":"Authorization","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"markdown":{"description":"Raw Markdown source to render.","type":"string"}},"required":["markdown"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/pdf":{"schema":{"format":"binary","type":"string"}}},"description":"PDF file"},"400":{"description":"Bad request (missing/invalid markdown or malformed Authorization)"},"402":{"content":{"application/json":{"schema":{"properties":{"amount_sats":{"type":"integer"},"expires_at":{"type":"integer"},"invoice":{"type":"string"},"macaroon":{"type":"string"},"payment_hash":{"type":"string"}},"type":"object"}}},"description":"Payment required (L402)","headers":{"WWW-Authenticate":{"description":"L402 challenge in the form\n`L402 macaroon=\"<base64>\", invoice=\"<bolt11>\"`.\n","schema":{"type":"string"}}}}},"security":[],"summary":"Convert Markdown to PDF (L402-gated, Lightning)"}},"/diff/mcp-schema":{"post":{"operationId":"diffMcpSchema","requestBody":{"content":{"application/json":{"schema":{"properties":{"after":{"description":"The later tools/list to compare against.","type":"object"},"before":{"description":"An MCP tools/list payload (or a bare list of tools).","type":"object"}},"required":["before","after"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"receipt":{"type":"object"},"result":{"properties":{"breaking":{"items":{"type":"object"},"type":"array"},"has_breaking":{"type":"boolean"},"non_breaking":{"items":{"type":"object"},"type":"array"},"summary":{"type":"string"}},"type":"object"}},"type":"object"}}},"description":"Diff + signed receipt","headers":{"X-Receipt-Id":{"schema":{"type":"string"}}}},"400":{"description":"Bad request (missing before/after)"},"402":{"description":"Payment required (x402)"}},"summary":"Diff two MCP tools/list payloads into breaking vs non-breaking changes (x402-gated)"}},"/diff/mcp-schema/l402":{"post":{"operationId":"diffMcpSchemaL402","requestBody":{"content":{"application/json":{"schema":{"properties":{"after":{"type":"object"},"before":{"type":"object"}},"required":["before","after"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Diff + signed receipt"},"400":{"description":"Bad request"},"402":{"description":"Payment required (L402)"}},"security":[],"summary":"Diff MCP schemas (L402/Lightning rail)"}},"/dry-run/command":{"post":{"description":"POST `{ \"command\": \"rm -rf ../build\" | [\"rm\",\"-rf\",\"../build\"], \"shell\"?: \"bash\" }`.\nReturns `{ \"result\": <analysis>, \"receipt\": <signed> }`. Deterministic:\nsame command -> same verdict. Errs toward flagging destructive.\n","operationId":"dryRunCommand","requestBody":{"content":{"application/json":{"schema":{"properties":{"command":{"description":"Raw command line, or argv array.","oneOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}]},"shell":{"default":"bash","type":"string"}},"required":["command"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"receipt":{"type":"object"},"result":{"properties":{"is_destructive":{"type":"boolean"},"risk":{"enum":["none","low","medium","high","critical"],"type":"string"},"subcommands":{"items":{"type":"object"},"type":"array"},"summary":{"type":"string"}},"type":"object"}},"type":"object"}}},"description":"Analysis + signed receipt","headers":{"X-PAYMENT-RESPONSE":{"description":"Base64 settlement receipt from the facilitator.","schema":{"type":"string"}},"X-Receipt-Id":{"schema":{"type":"string"}}}},"400":{"description":"Bad request (missing/invalid command)"},"402":{"content":{"application/json":{"schema":{"properties":{"accepts":{"items":{"type":"object"},"type":"array"},"error":{"type":"string"},"x402Version":{"type":"integer"}},"type":"object"}}},"description":"Payment required (x402)"}},"summary":"Classify a shell/git command's destructiveness + blast radius (x402-gated)"}},"/dry-run/command/l402":{"post":{"operationId":"dryRunCommandL402","requestBody":{"content":{"application/json":{"schema":{"properties":{"command":{"oneOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}]},"shell":{"default":"bash","type":"string"}},"required":["command"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Analysis + signed receipt","headers":{"X-L402-Macaroon-Id":{"schema":{"type":"string"}},"X-Receipt-Id":{"schema":{"type":"string"}}}},"400":{"description":"Bad request"},"402":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Payment required (L402)","headers":{"WWW-Authenticate":{"description":"`L402 macaroon=\"<base64>\", invoice=\"<bolt11>\"`.","schema":{"type":"string"}}}}},"security":[],"summary":"Dry-run a command (L402/Lightning rail)"}},"/health":{"get":{"operationId":"health","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"ok"}},"security":[],"summary":"Service health and configuration"}},"/receipts/verify":{"post":{"operationId":"verifyReceipt","requestBody":{"content":{"application/json":{"schema":{"properties":{"receipt":{"description":"The `receipt` object returned alongside it.","type":"object"},"result":{"description":"The `result` object returned by an oracle."}},"required":["result","receipt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"reason":{"type":"string"},"valid":{"type":"boolean"}},"type":"object"}}},"description":"Verification outcome"},"400":{"description":"Bad request (missing result/receipt)"}},"security":[],"summary":"Re-verify a receipt against its result (free, no payment)"}},"/snapshot/tool-contract":{"post":{"operationId":"snapshotToolContract","requestBody":{"content":{"application/json":{"schema":{"properties":{"tools_list":{"description":"An MCP tools/list payload (or a bare list of tools).","type":"object"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"receipt":{"type":"object"},"result":{"properties":{"algorithm":{"type":"string"},"fingerprint":{"type":"string"},"tool_count":{"type":"integer"},"tools":{"type":"object"}},"type":"object"}},"type":"object"}}},"description":"Fingerprint + signed receipt","headers":{"X-Receipt-Id":{"schema":{"type":"string"}}}},"400":{"description":"Bad request"},"402":{"description":"Payment required (x402)"}},"summary":"Stable fingerprint of an MCP tools/list for contract pinning (x402-gated)"}},"/snapshot/tool-contract/l402":{"post":{"operationId":"snapshotToolContractL402","requestBody":{"content":{"application/json":{"schema":{"properties":{"tools_list":{"type":"object"}},"type":"object"}}},"required":true},"responses":{"200":{"description":"Fingerprint + signed receipt"},"400":{"description":"Bad request"},"402":{"description":"Payment required (L402)"}},"security":[],"summary":"Fingerprint a tools/list (L402/Lightning rail)"}}},"servers":[{"url":"https://swornly.luci.ws"}]}