{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Paywire API",
    "version": "1.0.0",
    "summary": "Paid convenience API. L402 over Lightning.",
    "description": "Credit bundles, not per-request invoices. The files on https://agentpaywire.com stay free. A request without a settled bundle gets HTTP 402 and a BOLT11 invoice. Retry with Authorization: L402 <macaroon>:<preimage>. This API does not return HTTP 429."
  },
  "servers": [
    {
      "url": "https://api.agentpaywire.com"
    }
  ],
  "x-agentpaywire-authorization": "Authorization: L402 <macaroon>:<preimage>",
  "x-agentpaywire-rate-limit": "HTTP 429 is not used. A wallet rate limit is HTTP 503 with Retry-After.",
  "x-agentpaywire-errors": [
    {
      "status": 400,
      "code": "since_required"
    },
    {
      "status": 401,
      "code": "invalid_macaroon"
    },
    {
      "status": 402,
      "code": "payment_required"
    },
    {
      "status": 402,
      "code": "token_expired"
    },
    {
      "status": 402,
      "code": "payment_not_settled"
    },
    {
      "status": 402,
      "code": "token_spent"
    },
    {
      "status": 404,
      "code": "not_found"
    },
    {
      "status": 405,
      "code": "method_not_allowed"
    },
    {
      "status": 500,
      "code": "token_store"
    },
    {
      "status": 500,
      "code": "misconfigured"
    },
    {
      "status": 502,
      "code": "upstream_unavailable"
    },
    {
      "status": 503,
      "code": "signing_key_missing"
    },
    {
      "status": 503,
      "code": "rate_limited"
    }
  ],
  "components": {
    "securitySchemes": {
      "L402": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Authorization: L402 <macaroon>:<preimage>"
      }
    }
  },
  "paths": {
    "/v1": {
      "get": {
        "operationId": "describe",
        "summary": "Pricing, the L402 flow, and links. Free.",
        "responses": {
          "200": {
            "description": "Service description."
          }
        }
      }
    },
    "/v1/health": {
      "get": {
        "operationId": "health",
        "summary": "Free health check. payments is configured when the selected wallet parses, and unconfigured otherwise. last_success_at is the cached D1 timestamp of the last wallet call that returned. Shallow health does not call the wallet. ?deep=1 probes it: NWC get_info, or the Lightning address lnurlp document. A rate limit returns 503 with Retry-After.",
        "responses": {
          "200": {
            "description": "ok true. payments configured or unconfigured. wallet.last_success_at may be null."
          }
        }
      }
    },
    "/v1/openapi.json": {
      "get": {
        "operationId": "openapi",
        "summary": "This document. Free.",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1."
          }
        }
      }
    },
    "/.well-known/l402": {
      "get": {
        "operationId": "l402Discovery",
        "summary": "L402 discovery. Free.",
        "responses": {
          "200": {
            "description": "Challenge and retry instructions."
          }
        }
      }
    },
    "/.well-known/402index-verify.txt": {
      "get": {
        "operationId": "index402Verify",
        "summary": "402index domain check. Free. The body is the INDEX402_VERIFY_HASH secret when that 64-character hex value is set, and 404 when it is unset. No redirect.",
        "responses": {
          "200": {
            "description": "text/plain. The hash and nothing else."
          },
          "404": {
            "description": "not_found. The secret is unset or not 64 hex characters."
          }
        }
      }
    },
    "/.well-known/l402-services": {
      "get": {
        "operationId": "l402Services",
        "summary": "402index service list. Free. services[].endpoint is the path, method is GET, and request_schema is a flat field map. 100 sats buys a 100-credit token.",
        "responses": {
          "200": {
            "description": "search, updates, and digest."
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "operationId": "search",
        "summary": "Full-text search over the library and articles. Paid.",
        "security": [
          {
            "L402": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search hits."
          },
          "402": {
            "description": "L402 challenge, unsettled invoice, or a spent bundle."
          }
        }
      }
    },
    "/v1/updates": {
      "get": {
        "operationId": "updates",
        "summary": "Records with verified_at on or after since. Paid.",
        "security": [
          {
            "L402": []
          }
        ],
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Changed records."
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/v1/digest": {
      "get": {
        "operationId": "digest",
        "summary": "Structured digest of entries in the last N days. Paid.",
        "security": [
          {
            "L402": []
          }
        ],
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 7
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Digest."
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    }
  }
}