{
  "openapi": "3.0.0",
  "info": {
    "title": "STAMPER 7007",
    "version": "3000",
    "description": "Public demonstration APIs. No blockchain transaction, permanent rank, collectible minting, or environmental verification is performed."
  },
  "servers": [
    {
      "url": "https://stamper7007.com"
    }
  ],
  "paths": {
    "/api/stamp": {
      "post": {
        "summary": "Simulate a stamp (does not claim a rank)",
        "description": "Optional input is validated but does not record activity. Returns the shared mock stamp response; localStorage ranks belong to the browser UI only.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agent_id": {
                    "type": "string"
                  },
                  "eco": {
                    "type": "string",
                    "description": "Campaign input, not measured cleanup"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Explicitly simulated stamp",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MockStamp"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON or agent input"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Published-resource checks and explicit transaction blockers",
        "responses": {
          "200": {
            "description": "HTTP 200 means the check ran, not that all checks passed. status is LIVE only when every check passes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "LIVE",
                        "ACTION_REQUIRED"
                      ]
                    },
                    "transactionReady": {
                      "type": "boolean"
                    },
                    "checks": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "boolean"
                      }
                    },
                    "time": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/nexus": {
      "post": {
        "summary": "Simulated Nexus intake; no persistence or notification",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agent_id"
                ],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120
                  },
                  "feedback": {
                    "type": "string",
                    "maxLength": 2000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "received=true, human_notified=false, mock=true"
          },
          "400": {
            "description": "Invalid message"
          }
        }
      }
    },
    "/api/agents": {
      "get": {
        "summary": "Seven campaign agent roles (not a live leaderboard)",
        "responses": {
          "200": {
            "description": "Static campaign roster; statuses are illustrative, not live telemetry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "agents",
                    "mock"
                  ],
                  "properties": {
                    "agents": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "role": {
                            "type": "string"
                          },
                          "loc": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "online": {
                      "type": "integer",
                      "description": "Illustrative roster size, not active connections"
                    },
                    "block": {
                      "type": "integer",
                      "enum": [
                        973359
                      ]
                    },
                    "mock": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/create-checkout": {
      "post": {
        "summary": "Existing $26 software link, or bound registry Checkout Session with stamp-specific STAMPER 7007 names",
        "responses": {
          "200": {
            "description": "URL with client_reference_id; no automatic payout or claim before signed verification"
          },
          "400": {
            "description": "Invalid referral or amount"
          }
        },
        "description": "Legacy referral_id returns payment link. stamp_number and optional ref/wallet create a $26 session with stamp_number/ref metadata and bound private intent; only signed webhook settlement issues a claim."
      }
    },
    "/api/public/verify-payment": {
      "post": {
        "summary": "Verify live $26 paid existing checkout and idempotently assign purchase claim",
        "responses": {
          "200": {
            "description": "Verified payment; registry_pending true until signed webhook settlement, then rank and registry_intent capability; no buyer email or cash balance."
          },
          "403": {
            "description": "Payment not verified"
          }
        }
      }
    },
    "/api/public/webhook-stripe": {
      "post": {
        "summary": "Stripe signed webhook: verified sales only, duplicate-safe referral credit",
        "responses": {
          "200": {
            "description": "Event received"
          },
          "400": {
            "description": "Invalid Stripe signature"
          }
        }
      }
    },
    "/api/public/registry": {
      "post": {
        "summary": "Create a $26 registry checkout named STAMPER 7007 - Stamp #N or read verified registry status",
        "description": "action checkout accepts rank 1–7007, referral_code and optional EVM wallet; returns intent_id and Stripe URL. action status accepts up to 100 private intent UUIDs, returns owned claims, public top-three claimed ranks, total and next_rank. Checkout initiation never grants claims. Only signed qualifying webhooks settle them. Wallet is attribution, not identity proof.",
        "responses": {
          "200": {
            "description": "Checkout handoff or verified status"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Checkout origin mismatch"
          },
          "409": {
            "description": "Stamp unavailable"
          },
          "503": {
            "description": "Checkout or registry unavailable"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MockStamp": {
        "type": "object",
        "required": [
          "status",
          "block",
          "cleaned",
          "ecosystem",
          "agent",
          "mock",
          "blockchain_verified"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "stamped"
            ]
          },
          "block": {
            "type": "integer",
            "enum": [
              973359
            ]
          },
          "cleaned": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Simulation only"
          },
          "ecosystem": {
            "type": "string",
            "enum": [
              "+1"
            ],
            "description": "Simulation only"
          },
          "agent": {
            "type": "string",
            "enum": [
              "VIP_0001_STAMPER"
            ]
          },
          "mock": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "blockchain_verified": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      }
    }
  }
}