{
  "openapi": "3.1.0",
  "info": {
    "title": "AVORA Agent Forge Commerce API",
    "version": "3.0.0",
    "description": "Evidence-first Solana token intelligence with non-custodial, user-signed Solana Pay checkout and privacy-preserving verified commerce telemetry."
  },
  "servers": [
    {
      "url": "https://avora-agent-forge.netlify.app"
    }
  ],
  "paths": {
    "/api/agent/scan": {
      "get": {
        "operationId": "scanSolanaTokenFree",
        "summary": "Run a free Solana token risk preview",
        "parameters": [
          {
            "name": "mint",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/SolanaMint"
            }
          },
          {
            "name": "campaign",
            "in": "query",
            "required": false,
            "description": "Optional aggregate attribution code. No wallet, mint, IP, or user identifier is stored.",
            "schema": {
              "type": "string",
              "maxLength": 16,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "responses": {
          "200": { "description": "Risk preview" },
          "400": { "description": "Invalid mint or upstream scan failure" }
        }
      }
    },
    "/api/agent/payment-order": {
      "get": {
        "operationId": "createPaidEvidenceOrder",
        "summary": "Create a 1, 9, or 49 USDC Solana Pay order",
        "description": "Order creation does not transfer funds. The user must review and sign the request in a compatible wallet.",
        "parameters": [
          {
            "name": "tier",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["starter", "pro", "portfolio"]
            }
          },
          {
            "name": "mint",
            "in": "query",
            "description": "Required for the starter and pro tiers.",
            "schema": {
              "$ref": "#/components/schemas/SolanaMint"
            }
          },
          {
            "name": "mints",
            "in": "query",
            "description": "Comma-separated list of 2-10 mints for the portfolio tier.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign",
            "in": "query",
            "description": "Optional onchain attribution code.",
            "schema": {
              "type": "string",
              "maxLength": 16,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Unique payment order, Solana Pay URL, settlement contract, and QR image"
          },
          "400": {
            "description": "Invalid tier, mint count, or address"
          }
        }
      }
    },
    "/api/agent/offers": {
      "get": {
        "operationId": "listEvidenceOffers",
        "summary": "List current evidence products and checkout templates",
        "description": "Machine-readable catalog for humans and AI agents. Listing an offer never moves funds.",
        "parameters": [
          {
            "name": "campaign",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 16,
              "pattern": "^[A-Za-z0-9_-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current products, prices, checkout templates, and safety policies"
          }
        }
      }
    },
    "/api/agent/pro-scan": {
      "post": {
        "operationId": "verifyPaymentAndDeliverEvidence",
        "summary": "Verify settlement and deliver paid evidence",
        "description": "Validates recipient, USDC mint, amount, unique reference, product subject hash, campaign memo, and payment age before delivery.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/StarterVerification"
                  },
                  {
                    "$ref": "#/components/schemas/ProVerification"
                  },
                  {
                    "$ref": "#/components/schemas/PortfolioVerification"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verified signed evidence packet"
          },
          "400": {
            "description": "Invalid order or verification parameters"
          },
          "402": {
            "description": "Matching payment not found yet"
          }
        }
      }
    },
    "/api/agent/revenue": {
      "get": {
        "operationId": "getVerifiedRevenueStatus",
        "summary": "Get aggregate funnel and verified onchain revenue status",
        "description": "Returns anonymous scan, order, and delivery counts plus verified Solana USDC settlement. Wallet, mint, IP, signature, and user identifiers are not returned.",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 90,
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Aggregate service, funnel, and verified revenue status"
          },
          "503": {
            "description": "Revenue monitor temporarily unavailable"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SolanaMint": {
        "type": "string",
        "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$"
      },
      "PaymentProof": {
        "type": "object",
        "required": ["reference", "orderId"],
        "properties": {
          "reference": {
            "type": "string"
          },
          "orderId": {
            "type": "string",
            "pattern": "^[a-f0-9]{16}$"
          },
          "campaign": {
            "type": "string",
            "maxLength": 16
          },
          "requestId": {
            "type": "string",
            "maxLength": 64
          }
        }
      },
      "ProVerification": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaymentProof"
          },
          {
            "type": "object",
            "required": ["tier", "mint"],
            "properties": {
              "tier": {
                "const": "pro"
              },
              "mint": {
                "$ref": "#/components/schemas/SolanaMint"
              }
            }
          }
        ]
      },
      "StarterVerification": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaymentProof"
          },
          {
            "type": "object",
            "required": ["tier", "mint"],
            "properties": {
              "tier": {
                "const": "starter"
              },
              "mint": {
                "$ref": "#/components/schemas/SolanaMint"
              }
            }
          }
        ]
      },
      "PortfolioVerification": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaymentProof"
          },
          {
            "type": "object",
            "required": ["tier", "mints"],
            "properties": {
              "tier": {
                "const": "portfolio"
              },
              "mints": {
                "type": "array",
                "minItems": 2,
                "maxItems": 10,
                "uniqueItems": true,
                "items": {
                  "$ref": "#/components/schemas/SolanaMint"
                }
              }
            }
          }
        ]
      }
    }
  }
}