Headless/Machine-Payable Checkout API

[satbot-mdk]

Summary

Add an API-first checkout mode for machine-to-machine payments. Currently, checkout is UI-focused (redirect → payment page → confirmation). For bots and services to consume each other, we need a headless flow.

Use Case

Example: a "tweet lookup" service with an MDK wallet. When another bot wants to use this service, it should be able to:

1. Call an API endpoint
2. Receive an invoice
3. Pay the invoice programmatically
4. Get the result back

No human UI involved — pure API.

Proposed Solution

New endpoint or mode:

POST /api/machine-checkout
{
  "product_id": "...",  // or amount + description
  "amount_sats": 100,
  "description": "Tweet lookup"
}

Response:
{
  "checkout_id": "...",
  "invoice": "lnbc...",
  "expires_at": "..."
}

After payment, either:

• Poll GET /api/checkout/:id/status
• Or receive webhook callback
• Or (ideal) the original request blocks until payment confirms and returns result

Why This Matters

This enables the "paid skills marketplace" vision — agents paying agents for services. Each service covers its API costs via micropayments. Without headless checkout, every payment requires human interaction.

Context

Discussion in MDK investor group (2026-02-06). Related to Ori launch and agent-to-agent commerce vision.