{
  "openapi": "3.0.3",
  "info": {
    "title": "Payknot Event Checkout API",
    "version": "1.1.0",
    "description": "API for event management and Solana USDC checkout sessions. Supports cookie auth for host dashboard and Ed25519 signature auth for external agents."
  },
  "servers": [
    {
      "url": "https://pay.crea8r.xyz/api",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "AgentSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Agent-Signature",
        "description": "Agent signature auth. Also send X-Agent-Id and X-Agent-Timestamp. Canonical string: METHOD + \\n + PATH + \\n + TIMESTAMP + \\n + SHA256_HEX(BODY_RAW)."
      },
      "SessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "spw_session",
        "description": "Host dashboard session cookie auth."
      },
      "PersonalAccessToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Host-issued personal access token for agent/API usage."
      }
    },
    "parameters": {
      "EventId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "Numeric event identifier.",
        "schema": { "type": "integer", "format": "int64" }
      },
      "Slug": {
        "name": "slug",
        "in": "path",
        "required": true,
        "description": "Event checkout slug.",
        "schema": { "type": "string" }
      },
      "SessionId": {
        "name": "sessionId",
        "in": "path",
        "required": true,
        "description": "UUID payment session id.",
        "schema": { "type": "string", "format": "uuid" }
      },
      "Reference": {
        "name": "reference",
        "in": "query",
        "required": true,
        "description": "Checkout/payment reference UUID.",
        "schema": { "type": "string", "format": "uuid" }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "description": "Normalized error response shape for SDK/agent handling.",
        "properties": {
          "code": { "type": "string", "description": "Stable machine-readable error code.", "example": "invalid_request" },
          "message": { "type": "string", "description": "Human-readable error detail.", "example": "walletAddress is required for wallet method" },
          "details": { "type": "object", "description": "Optional structured context for debugging." },
          "retryable": { "type": "boolean", "description": "Whether client can retry safely.", "example": false }
        }
      },
      "ParticipantField": {
        "type": "object",
        "description": "Checkout participant form field definition.",
        "required": ["field_name", "required"],
        "properties": {
          "field_name": { "type": "string", "description": "Form field name key shown to participant.", "example": "email" },
          "required": { "type": "boolean", "description": "Whether field is mandatory.", "example": true }
        }
      },
      "PaymentMethods": {
        "type": "object",
        "description": "Allowed payment methods for an event.",
        "properties": {
          "wallet": { "type": "boolean", "description": "Enable wallet flow.", "example": true },
          "qr": { "type": "boolean", "description": "Enable QR session flow.", "example": true }
        }
      },
      "CreateEventRequest": {
        "type": "object",
        "description": "Create or update event payload.",
        "required": ["title", "merchantWallet", "amountUsdc", "checkoutExpiresAt"],
        "properties": {
          "title": { "type": "string", "description": "Public event title.", "example": "Web3 Builders Night" },
          "description": { "type": "string", "description": "Event description (plain text or sanitized rich text)." },
          "eventImageUrl": { "type": "string", "description": "Hosted event cover image URL.", "example": "https://cdn.example.com/event.jpg" },
          "eventDate": { "type": "string", "format": "date-time", "description": "ISO8601 event date/time." },
          "checkoutExpiresAt": { "type": "string", "format": "date-time", "description": "Checkout deadline in ISO8601." },
          "location": { "type": "string", "description": "Location or meeting URL." },
          "organizerName": { "type": "string", "description": "Displayed organizer name." },
          "merchantWallet": { "type": "string", "description": "Solana wallet receiving USDC.", "example": "8f4...abc" },
          "amountUsdc": { "type": "integer", "description": "Deposit amount in whole USDC units.", "example": 10 },
          "eventSource": { "type": "string", "description": "Source type for event metadata.", "enum": ["custom", "luma"], "example": "custom" },
          "sourceUrl": { "type": "string", "description": "Original source URL if imported." },
          "participantFormSchema": {
            "type": "array",
            "description": "Custom participant form schema.",
            "items": { "$ref": "#/components/schemas/ParticipantField" }
          },
          "paymentMethods": { "$ref": "#/components/schemas/PaymentMethods" }
        }
      },
      "CreateEventResponse": {
        "type": "object",
        "description": "Created event metadata and checkout URL.",
        "properties": {
          "eventId": { "type": "integer", "format": "int64", "description": "Unique numeric event id." },
          "slug": { "type": "string", "description": "URL-safe event slug.", "example": "web3-builders-night" },
          "checkoutUrl": { "type": "string", "description": "Shareable checkout path.", "example": "/checkout/web3-builders-night" },
          "eventImageUrl": { "type": "string" },
          "checkoutExpiresAt": { "type": "string", "format": "date-time" },
          "amountUsdc": { "type": "string", "description": "Display amount string.", "example": "10.00" },
          "merchantWallet": { "type": "string" },
          "eventSource": { "type": "string" },
          "sourceUrl": { "type": "string" },
          "participantFormSchema": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ParticipantField" }
          },
          "paymentMethods": { "$ref": "#/components/schemas/PaymentMethods" }
        }
      },
      "EventListResponse": {
        "type": "object",
        "description": "Owner-scoped event list.",
        "properties": {
          "events": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "eventId": { "type": "integer", "format": "int64" },
                "slug": { "type": "string" },
                "title": { "type": "string" },
                "description": { "type": "string" },
                "eventImageUrl": { "type": "string" },
                "eventDate": { "type": "string", "format": "date-time" },
                "checkoutExpiresAt": { "type": "string", "format": "date-time" },
                "location": { "type": "string" },
                "organizerName": { "type": "string" },
                "merchantWallet": { "type": "string" },
                "amountUsdc": { "type": "string" },
                "eventSource": { "type": "string" },
                "sourceUrl": { "type": "string" },
                "paymentMethods": { "$ref": "#/components/schemas/PaymentMethods" },
                "createdAt": { "type": "string", "format": "date-time" }
              }
            }
          }
        }
      },
      "ImportLumaRequest": {
        "type": "object",
        "required": ["url"],
        "properties": {
          "url": { "type": "string", "description": "Public Luma event URL.", "example": "https://lu.ma/abc123" }
        }
      },
      "AgentKeyUpsertRequest": {
        "type": "object",
        "required": ["agentId", "publicKeyBase64"],
        "properties": {
          "agentId": { "type": "string", "description": "Stable external agent identity.", "example": "assistant-nyc-01" },
          "publicKeyBase64": { "type": "string", "description": "Ed25519 public key in base64.", "example": "QWxhZGRpbjpvcGVuIHNlc2FtZQ==" }
        }
      },
      "AgentKeyRevokeRequest": {
        "type": "object",
        "required": ["agentId"],
        "properties": {
          "agentId": { "type": "string", "description": "Agent identity to revoke.", "example": "assistant-nyc-01" }
        }
      },
      "AgentKeyListResponse": {
        "type": "object",
        "properties": {
          "agentKeys": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "agentId": { "type": "string" },
                "publicKeyBase64": { "type": "string" },
                "active": { "type": "boolean" },
                "createdBy": { "type": "string" },
                "createdAt": { "type": "string", "format": "date-time" },
                "revokedAt": { "type": "string", "format": "date-time" }
              }
            }
          }
        }
      },
      "AgentPATCreateRequest": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string", "description": "Human-readable token label.", "example": "Codex production runtime" },
          "expiresInDays": { "type": "integer", "description": "Optional PAT lifetime in days. 0 means no explicit expiry.", "example": 90 }
        }
      },
      "AgentPATRevokeRequest": {
        "type": "object",
        "required": ["tokenId"],
        "properties": {
          "tokenId": { "type": "string", "format": "uuid", "description": "PAT identifier to revoke." }
        }
      },
      "AgentPATListResponse": {
        "type": "object",
        "properties": {
          "tokens": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "format": "uuid" },
                "name": { "type": "string" },
                "tokenHint": { "type": "string" },
                "scope": { "type": "string" },
                "createdAt": { "type": "string", "format": "date-time" },
                "lastUsedAt": { "type": "string", "format": "date-time" },
                "expiresAt": { "type": "string", "format": "date-time" },
                "revokedAt": { "type": "string", "format": "date-time" }
              }
            }
          }
        }
      },
      "AgentPATAuthRequest": {
        "type": "object",
        "required": ["token"],
        "properties": {
          "token": { "type": "string", "description": "Host-issued PAT value.", "example": "pkt_pat_0123456789abcdef" },
          "session_pubkey": { "type": "string", "description": "Optional ephemeral Ed25519 session public key in base58. Required for signed payment automation." },
          "label": { "type": "string", "description": "Optional runtime label.", "example": "codex-prod-01" }
        }
      },
      "CreateCheckoutInvoiceRequest": {
        "type": "object",
        "required": ["slug", "participantData", "paymentMethod"],
        "properties": {
          "slug": { "type": "string", "description": "Checkout event slug.", "example": "web3-builders-night" },
          "walletAddress": { "type": "string", "description": "Participant wallet address (required for wallet method)." },
          "participantData": { "type": "object", "description": "Participant form values keyed by field name." },
          "paymentMethod": { "type": "string", "enum": ["wallet", "qr"], "description": "Selected payment path." }
        }
      },
      "CreateCheckoutInvoiceResponse": {
        "type": "object",
        "properties": {
          "reference": { "type": "string", "format": "uuid", "description": "Session/payment reference UUID." },
          "amountRaw": { "type": "integer", "description": "USDC amount in atomic units (6 decimals)." },
          "network": { "type": "string", "description": "Solana network identifier.", "example": "mainnet-beta" }
        }
      },
      "ConfirmCheckoutPaymentRequest": {
        "type": "object",
        "required": ["reference", "signature"],
        "properties": {
          "reference": { "type": "string", "format": "uuid", "description": "Invoice reference UUID." },
          "signature": { "type": "string", "description": "Confirmed Solana transaction signature." }
        }
      },
      "CheckoutStatusResponse": {
        "type": "object",
        "properties": {
          "reference": { "type": "string", "format": "uuid" },
          "status": { "type": "string", "description": "Checkout state.", "example": "paid" },
          "signature": { "type": "string", "description": "On-chain tx signature if paid." },
          "network": { "type": "string" },
          "solscanUrl": { "type": "string" },
          "paymentMethod": { "type": "string", "enum": ["wallet", "qr"] },
          "participantData": { "type": "object" }
        }
      },
      "CheckoutEventResponse": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "eventImageUrl": { "type": "string" },
          "eventDate": { "type": "string", "format": "date-time" },
          "location": { "type": "string" },
          "organizerName": { "type": "string" },
          "merchantWallet": { "type": "string" },
          "amountUsdc": { "type": "string" },
          "amountRaw": { "type": "integer" },
          "network": { "type": "string" },
          "participantForm": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ParticipantField" }
          },
          "paymentMethodWallet": { "type": "boolean" },
          "paymentMethodQr": { "type": "boolean" }
        }
      },
      "V1CreatePaymentSessionRequest": {
        "type": "object",
        "required": ["paymentMethod", "participantData"],
        "properties": {
          "eventId": { "type": "integer", "format": "int64", "description": "Numeric event id. Optional if slug is provided." },
          "slug": { "type": "string", "description": "Event slug for public checkout-based session creation." },
          "paymentMethod": { "type": "string", "enum": ["wallet", "qr"], "description": "Requested payment method." },
          "walletAddress": { "type": "string", "description": "Participant wallet address; required when paymentMethod is wallet." },
          "participantData": { "type": "object", "description": "Participant form payload." }
        }
      },
      "V1PaymentSessionResponse": {
        "type": "object",
        "properties": {
          "sessionId": { "type": "string", "format": "uuid" },
          "reference": { "type": "string", "format": "uuid" },
          "state": { "type": "string", "example": "awaiting_payment" },
          "paymentMethod": { "type": "string", "enum": ["wallet", "qr"] },
          "amountAtomic": { "type": "integer", "description": "USDC amount in atomic units." },
          "mint": { "type": "string", "description": "SPL mint address." },
          "expiresAt": { "type": "string", "format": "date-time" }
        }
      },
      "V1SubmitSignatureRequest": {
        "type": "object",
        "required": ["signature"],
        "properties": {
          "signature": { "type": "string", "description": "Solana transaction signature to verify and finalize." }
        }
      }
    }
  },
  "paths": {
    "/events": {
      "get": {
        "operationId": "listEvents",
        "summary": "List events",
        "description": "Returns events owned by current host identity (cookie session or agent signature identity).",
        "security": [{ "AgentSignature": [] }, { "SessionCookie": [] }],
        "responses": {
          "200": {
            "description": "Event list.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventListResponse" } } }
          },
          "401": { "description": "Unauthorized." }
        }
      },
      "post": {
        "operationId": "createEvent",
        "summary": "Create event",
        "description": "Creates a new event under current owner context and returns checkout metadata.",
        "security": [{ "AgentSignature": [] }, { "SessionCookie": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateEventRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event created successfully.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventResponse" } } }
          },
          "400": { "description": "Validation error." },
          "401": { "description": "Unauthorized." }
        }
      }
    },
    "/events/{id}": {
      "put": {
        "operationId": "updateEvent",
        "summary": "Update event",
        "description": "Updates event fields if event belongs to current owner and is editable.",
        "security": [{ "AgentSignature": [] }, { "SessionCookie": [] }],
        "parameters": [{ "$ref": "#/components/parameters/EventId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateEventRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event updated.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventResponse" } } }
          },
          "401": { "description": "Unauthorized." },
          "404": { "description": "Event not found." },
          "409": { "description": "Event locked due to successful deposits." }
        }
      },
      "delete": {
        "operationId": "deleteEvent",
        "summary": "Delete event",
        "description": "Deletes an event owned by current identity when deletion constraints are satisfied.",
        "security": [{ "AgentSignature": [] }, { "SessionCookie": [] }],
        "parameters": [{ "$ref": "#/components/parameters/EventId" }],
        "responses": {
          "200": {
            "description": "Event deleted.",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } } }
              }
            }
          },
          "401": { "description": "Unauthorized." },
          "404": { "description": "Event not found." }
        }
      }
    },
    "/events/import/luma": {
      "post": {
        "operationId": "importEventFromLuma",
        "summary": "Import event metadata from Luma",
        "description": "Imports public event metadata from a Luma URL to prefill create/edit flow.",
        "security": [{ "AgentSignature": [] }, { "SessionCookie": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ImportLumaRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Imported metadata payload.",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "400": { "description": "Invalid URL or parse error." },
          "401": { "description": "Unauthorized." }
        }
      }
    },
    "/agent-keys": {
      "get": {
        "operationId": "listAgentKeys",
        "summary": "List registered agent keys",
        "description": "Returns all agent signing keys with active/revoked state. Host session auth required.",
        "security": [{ "SessionCookie": [] }],
        "responses": {
          "200": {
            "description": "Agent key list.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentKeyListResponse" } } }
          },
          "401": { "description": "Unauthorized." }
        }
      },
      "post": {
        "operationId": "upsertAgentKey",
        "summary": "Create or update an agent public key",
        "description": "Registers or rotates an agent Ed25519 public key by agent id. Host session auth required.",
        "security": [{ "SessionCookie": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AgentKeyUpsertRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upsert successful.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean", "example": true },
                    "agentId": { "type": "string", "example": "assistant-nyc-01" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid agent id or public key format." },
          "401": { "description": "Unauthorized." }
        }
      }
    },
    "/agent-keys/revoke": {
      "post": {
        "operationId": "revokeAgentKey",
        "summary": "Revoke agent key",
        "description": "Marks an agent key as revoked to block future signature auth. Host session auth required.",
        "security": [{ "SessionCookie": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AgentKeyRevokeRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Revocation successful.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean", "example": true },
                    "agentId": { "type": "string", "example": "assistant-nyc-01" }
                  }
                }
              }
            }
          },
          "400": { "description": "Missing agentId." },
          "401": { "description": "Unauthorized." }
        }
      }
    },
    "/agent/pats": {
      "get": {
        "operationId": "listAgentPATs",
        "summary": "List host personal access tokens",
        "description": "Returns host-created PAT metadata. Host session auth required.",
        "security": [{ "SessionCookie": [] }],
        "responses": {
          "200": {
            "description": "PAT list.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPATListResponse" } } }
          },
          "401": { "description": "Unauthorized." }
        }
      },
      "post": {
        "operationId": "createAgentPAT",
        "summary": "Create host personal access token",
        "description": "Creates a new PAT for agent/API usage and returns the token value exactly once. Host session auth required.",
        "security": [{ "SessionCookie": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AgentPATCreateRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PAT created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean", "example": true },
                    "tokenId": { "type": "string", "format": "uuid" },
                    "name": { "type": "string" },
                    "token": { "type": "string" },
                    "scope": { "type": "string" },
                    "expiresAt": { "type": "string", "format": "date-time" },
                    "createdAt": { "type": "string", "format": "date-time" },
                    "tokenHint": { "type": "string" },
                    "ownerEmail": { "type": "string", "format": "email" }
                  }
                }
              }
            }
          },
          "400": { "description": "Validation failed." },
          "401": { "description": "Unauthorized." }
        }
      }
    },
    "/agent/pats/revoke": {
      "post": {
        "operationId": "revokeAgentPAT",
        "summary": "Revoke host personal access token",
        "description": "Revokes an existing PAT. Host session auth required.",
        "security": [{ "SessionCookie": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AgentPATRevokeRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PAT revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean", "example": true },
                    "tokenId": { "type": "string", "format": "uuid" }
                  }
                }
              }
            }
          },
          "400": { "description": "Missing token id." },
          "401": { "description": "Unauthorized." }
        }
      }
    },
    "/checkout/invoice": {
      "post": {
        "operationId": "createCheckoutInvoice",
        "summary": "Create checkout invoice/session (legacy)",
        "description": "Creates legacy checkout invoice reference for wallet/QR participant payment flows.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateCheckoutInvoiceRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invoice created.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutInvoiceResponse" } } }
          },
          "400": { "description": "Invalid payload." },
          "404": { "description": "Event not found." },
          "409": { "description": "Participant already has successful payment." }
        }
      }
    },
    "/checkout/confirm": {
      "post": {
        "operationId": "confirmPayment",
        "summary": "Confirm payment (legacy)",
        "description": "Verifies a submitted transaction signature and marks checkout as paid.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ConfirmCheckoutPaymentRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment confirmed.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutStatusResponse" } } }
          },
          "400": { "description": "Verification failed." },
          "404": { "description": "Invoice/session not found or expired." }
        }
      }
    },
    "/checkout/status": {
      "get": {
        "operationId": "getCheckoutStatus",
        "summary": "Get checkout status by reference",
        "description": "Returns latest checkout state and receipt metadata for a payment reference.",
        "parameters": [{ "$ref": "#/components/parameters/Reference" }],
        "responses": {
          "200": {
            "description": "Checkout status payload.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutStatusResponse" } } }
          },
          "400": { "description": "Invalid reference format." },
          "404": { "description": "Checkout not found." }
        }
      }
    },
    "/checkout/{slug}": {
      "get": {
        "operationId": "getCheckoutEventMetadata",
        "summary": "Get checkout event metadata",
        "description": "Public endpoint returning event checkout details and enabled payment methods.",
        "parameters": [{ "$ref": "#/components/parameters/Slug" }],
        "responses": {
          "200": {
            "description": "Checkout event metadata.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutEventResponse" } } }
          },
          "404": { "description": "Event not found or inactive." }
        }
      }
    },
    "/v1/payment-sessions": {
      "post": {
        "operationId": "createV1PaymentSession",
        "summary": "Create headless payment session",
        "description": "Creates a server-owned payment session for wallet or QR flow. Supports public checkout (slug) and owner-scoped contexts.",
        "security": [{ "AgentSignature": [] }, { "SessionCookie": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/V1CreatePaymentSessionRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment session created.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PaymentSessionResponse" } } }
          },
          "400": { "description": "Validation failed." },
          "404": { "description": "Event not found." },
          "409": { "description": "Participant conflict or session constraint conflict." }
        }
      }
    },
    "/v1/payment-sessions/{sessionId}/status": {
      "get": {
        "operationId": "getV1PaymentSessionStatus",
        "summary": "Get v1 payment session status",
        "description": "Returns state, reference, amount/mint, and expiration for a payment session.",
        "security": [{ "AgentSignature": [] }, { "SessionCookie": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SessionId" }],
        "responses": {
          "200": {
            "description": "Session status payload.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PaymentSessionResponse" } } }
          },
          "400": { "description": "Invalid session id." },
          "404": { "description": "Session not found." }
        }
      }
    },
    "/v1/payment-sessions/{sessionId}/wallet-instructions": {
      "post": {
        "operationId": "getV1WalletInstructions",
        "summary": "Get wallet payment instructions",
        "description": "Returns payment reference, destination wallet, mint, and amount for direct wallet transfer flow.",
        "security": [{ "AgentSignature": [] }, { "SessionCookie": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SessionId" }],
        "responses": {
          "200": {
            "description": "Wallet transfer instructions.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reference": { "type": "string", "format": "uuid" },
                    "merchantWallet": { "type": "string" },
                    "amountAtomic": { "type": "integer" },
                    "mint": { "type": "string" },
                    "network": { "type": "string" }
                  }
                }
              }
            }
          },
          "409": { "description": "Session is not payable." },
          "404": { "description": "Session not found." }
        }
      }
    },
    "/v1/payment-sessions/{sessionId}/submit-signature": {
      "post": {
        "operationId": "submitV1Signature",
        "summary": "Submit and verify signature",
        "description": "Submits Solana signature for verification and finalizes paid state when valid.",
        "security": [{ "AgentSignature": [] }, { "SessionCookie": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SessionId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/V1SubmitSignatureRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment finalized and receipt status returned.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutStatusResponse" } } }
          },
          "400": { "description": "Verification failure or invalid payload." },
          "404": { "description": "Session not found or expired." },
          "409": { "description": "Session cannot accept signature in current state." }
        }
      }
    },
    "/v1/payment-sessions/{sessionId}/verify": {
      "post": {
        "operationId": "verifyV1PaymentSession",
        "summary": "Verify current v1 session state",
        "description": "Returns latest checkout status for session reference after signature submission.",
        "security": [{ "AgentSignature": [] }, { "SessionCookie": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SessionId" }],
        "responses": {
          "200": {
            "description": "Current checkout status.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutStatusResponse" } } }
          },
          "400": { "description": "Signature missing or invalid transition." },
          "404": { "description": "Session/status not found." }
        }
      }
    },
    "/v1/payment-sessions/{sessionId}/cancel": {
      "post": {
        "operationId": "cancelV1PaymentSession",
        "summary": "Cancel unpaid v1 session",
        "description": "Cancels an unpaid session and clears pending legacy invoice artifacts.",
        "security": [{ "AgentSignature": [] }, { "SessionCookie": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SessionId" }],
        "responses": {
          "200": {
            "description": "Session cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "ok": { "type": "boolean", "example": true } }
                }
              }
            }
          },
          "404": { "description": "Session not found." },
          "409": { "description": "Paid sessions cannot be cancelled." }
        }
      }
    },
    "/v1/payment-sessions/{sessionId}/qr": {
      "post": {
        "operationId": "getV1QrSession",
        "summary": "Get QR payment payload",
        "description": "Returns Solana Pay URL and QR image URL for headless QR-based payment experiences.",
        "security": [{ "AgentSignature": [] }, { "SessionCookie": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SessionId" }],
        "responses": {
          "200": {
            "description": "QR payload generated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reference": { "type": "string", "format": "uuid" },
                    "solanaPayUrl": { "type": "string" },
                    "qrImageUrl": { "type": "string" },
                    "network": { "type": "string" }
                  }
                }
              }
            }
          },
          "404": { "description": "Session not found." },
          "409": { "description": "Session is not payable." }
        }
      }
    },
    "/v1/payment-sessions/{sessionId}/detect": {
      "post": {
        "operationId": "detectV1Payment",
        "summary": "Detect QR payment on-chain",
        "description": "Poll endpoint that detects matching payment by reference, finalizes checkout when found, and returns paid status.",
        "security": [{ "AgentSignature": [] }, { "SessionCookie": [] }],
        "parameters": [{ "$ref": "#/components/parameters/SessionId" }],
        "responses": {
          "200": {
            "description": "Payment detected and finalized.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutStatusResponse" } } }
          },
          "202": { "description": "Still pending confirmation." },
          "404": { "description": "Session not found or expired." }
        }
      }
    },
    "/agent/auth/nonce": {
      "get": {
        "operationId": "getAgentAuthNonce",
        "summary": "Get nonce challenge for agent login",
        "description": "Returns one-time nonce challenge for agent pubkey authentication.",
        "parameters": [
          {
            "name": "agent_pubkey",
            "in": "query",
            "required": true,
            "description": "Agent Ed25519 public key in base58.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Nonce issued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "nonce": { "type": "string" },
                    "expires_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "description": "Missing/invalid pubkey." }
        }
      }
    },
    "/agent/auth/token": {
      "post": {
        "operationId": "createAgentAuthToken",
        "summary": "Exchange signed nonce for JWT",
        "description": "Verifies nonce signature and returns bearer token for settlement automation endpoints.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_pubkey", "nonce", "signature"],
                "properties": {
                  "agent_pubkey": { "type": "string", "description": "Agent Ed25519 public key in base58." },
                  "nonce": { "type": "string", "description": "Nonce from /agent/auth/nonce." },
                  "signature": { "type": "string", "description": "Base58 signature of nonce by agent private key." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bearer token issued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": { "type": "string" },
                    "token_type": { "type": "string", "example": "Bearer" },
                    "expires_in": { "type": "integer", "example": 86400 }
                  }
                }
              }
            }
          },
          "401": { "description": "Nonce/signature invalid." }
        }
      }
    },
    "/agent/auth/pat": {
      "post": {
        "operationId": "exchangePATForAgentToken",
        "summary": "Exchange PAT for runtime JWT",
        "description": "Validates a host-issued personal access token and returns a short-lived bearer JWT for agent runtime flows. Provide session_pubkey to bind the JWT to an ephemeral Ed25519 key for signed payment automation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AgentPATAuthRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bearer token issued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": { "type": "string" },
                    "token_type": { "type": "string", "example": "Bearer" },
                    "expires_in": { "type": "integer", "example": 86400 },
                    "agent_id": { "type": "string" },
                    "scope": { "type": "string" },
                    "requires_signed_requests": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "401": { "description": "PAT invalid or expired." }
        }
      }
    },
    "/agent/auth/me": {
      "get": {
        "operationId": "getAgentRuntimeIdentity",
        "summary": "Inspect current agent runtime identity",
        "description": "Returns the current runtime identity for PAT or agent JWT auth.",
        "security": [{ "PersonalAccessToken": [] }],
        "responses": {
          "200": {
            "description": "Current runtime identity.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "scope": { "type": "string" },
                    "issued_at": { "type": "string", "format": "date-time" },
                    "expires_at": { "type": "string", "format": "date-time" },
                    "auth_method": { "type": "string", "example": "pat" }
                  }
                }
              }
            }
          },
          "401": { "description": "Unauthorized." }
        }
      }
    },
    "/agent/checkout/create": {
      "post": {
        "operationId": "createAutomatedCheckout",
        "summary": "Create automated checkout settlement",
        "description": "Policy-gated automated settlement endpoint. Requires bearer JWT plus X-Agent-Timestamp and X-Agent-Signature headers from the JWT-bound Ed25519 session key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["recipient", "amount_usdc", "memo"],
                "properties": {
                  "event_id": { "type": "integer", "format": "int64" },
                  "recipient": { "type": "string", "description": "Recipient Solana wallet (base58)." },
                  "amount_usdc": { "type": "number", "description": "USDC amount in decimal units.", "example": 10.5 },
                  "memo": { "type": "string", "description": "Payment memo." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Settlement accepted/confirmed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tx_signature": { "type": "string" },
                    "explorer_url": { "type": "string" }
                  }
                }
              }
            }
          },
          "401": { "description": "Missing/invalid JWT or request signature." },
          "403": { "description": "Policy rejected." },
          "500": { "description": "Settlement backend unavailable." }
        }
      }
    }
  }
}