{
  "openapi": "3.1.0",
  "info": {
    "title": "Agentic Cards reputation scanner",
    "version": "1.0.0",
    "description": "Public, keyless API for Agentic Cards on BNB Chain (chainId 56). GET /score returns a wallet's on-chain reputation (wallet age, transactions, active days, NFTs, loyalty), its rank, the $CARDS it will receive and an EIP-712 signature to pass straight into AgenticCards.mint(). Only wallets that own a .ai Agent ID can mint."
  },
  "servers": [
    {
      "url": "https://agentic-cards.pages.dev/api"
    }
  ],
  "paths": {
    "/score": {
      "get": {
        "operationId": "getScore",
        "summary": "Reputation score + signed mint payload for a wallet",
        "parameters": [
          {
            "name": "wallet",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{40}$"
            },
            "description": "The wallet that will send mint() (msg.sender)."
          }
        ],
        "responses": {
          "200": {
            "description": "Score. `signature` is null when the wallet has no Agent ID (eligible=false).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Score"
                }
              }
            }
          },
          "400": {
            "description": "Bad wallet address"
          },
          "429": {
            "description": "Rate limited (30/min/IP); retry after 60 s"
          },
          "502": {
            "description": "Upstream RPC failed; retry"
          }
        }
      }
    },
    "/collection": {
      "get": {
        "operationId": "getCollection",
        "summary": "Collection stats: minted, supply, price, addresses (cached 30 s)",
        "responses": {
          "200": {
            "description": "Stats",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Collection"
                }
              }
            }
          }
        }
      }
    },
    "/card/{tokenId}": {
      "get": {
        "operationId": "getCard",
        "summary": "Decoded on-chain metadata, owner and mint message for one card (cached 1 h)",
        "parameters": [
          {
            "name": "tokenId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Card"
          },
          "404": {
            "description": "Not minted"
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "health",
        "summary": "Signer address, contract, chainId",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Score": {
        "type": "object",
        "properties": {
          "wallet": {
            "type": "string"
          },
          "handle": {
            "type": [
              "string",
              "null"
            ],
            "description": "Agent ID name without .ai"
          },
          "eligible": {
            "type": "boolean"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000
          },
          "rank": {
            "type": "string",
            "enum": [
              "Recruit",
              "Operative",
              "Specialist",
              "Commander",
              "Elite",
              "Legendary"
            ]
          },
          "breakdown": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100
            },
            "minItems": 5,
            "maxItems": 5,
            "description": "[AGE, TXNS, DAYS, NFTS, LOYALTY]"
          },
          "cardsAmount": {
            "type": "string",
            "description": "$CARDS in wei (18 decimals)"
          },
          "cards": {
            "type": "integer",
            "description": "$CARDS whole tokens (500..10000)"
          },
          "deadline": {
            "type": "integer",
            "description": "Unix time; signature valid until then (30 min)"
          },
          "signature": {
            "type": [
              "string",
              "null"
            ]
          },
          "mint": {
            "type": "object",
            "properties": {
              "to": {
                "type": "string"
              },
              "chainId": {
                "type": "integer"
              },
              "function": {
                "type": "string"
              },
              "args": {
                "type": "array",
                "description": "[score, breakdown, cardsAmount, deadline, signature] in mint() order"
              }
            }
          },
          "facts": {
            "type": "object",
            "description": "Raw signals: walletAgeDays, txs, activeDaysLast365, nftsCounted, loyalty, sources"
          }
        }
      },
      "Collection": {
        "type": "object",
        "properties": {
          "contract": {
            "type": "string"
          },
          "cardsToken": {
            "type": "string"
          },
          "minted": {
            "type": "integer"
          },
          "maxSupply": {
            "type": "integer"
          },
          "remaining": {
            "type": "integer"
          },
          "mintOpen": {
            "type": "boolean"
          },
          "mintPriceWei": {
            "type": "string"
          },
          "mintPriceBNB": {
            "type": "number"
          }
        }
      }
    }
  }
}
