openapi: 3.1.0
info:
  title: Wallet Labels MCP (x402)
  version: 0.1.0
  description: |
    Pay-per-call x402 endpoints for EVM wallet labels — composes ENS,
    OFAC SDN, Tornado Cash mixer registry, on-chain ERC-20 metadata, and
    a public-label registry into one view per address. Supports
    ethereum / base / arbitrum / optimism / polygon. No signup, no API key —
    pay USDC on Base. Each first call returns HTTP 402 with an x402
    envelope; sign X-PAYMENT and retry.
  contact:
    name: 
    url: 
    email: hello@
servers:
  - url: https://wallet-labels-mcp.mtree.workers.dev
x-pricing:
  - path: /v1/wallet/labels
    method: POST
    price: $0.05
    amount: "0.05"
    asset: USDC
    network: base
  - path: /v1/wallet/risk_score
    method: POST
    price: $0.10
    amount: "0.10"
    asset: USDC
    network: base
  - path: /v1/labels/by_category
    method: POST
    price: $0.07
    amount: "0.07"
    asset: USDC
    network: base
paths:
  /v1/wallet/labels:
    post:
      operationId: walletLabels
      summary: Composed labels for an EVM wallet
      description: |
        $0.05/call. Composes ENS + OFAC SDN + Tornado mixer registry +
        on-chain ERC-20 metadata + public-label registry into one view.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [address]
              properties:
                address:
                  type: string
                  description: EVM address (0x… 20 bytes)
                  example: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
                chain:
                  type: string
                  description: ethereum | base | arbitrum | optimism | polygon (default ethereum)
                  example: ethereum
      responses:
        "200":
          description: Composed label view
        "402":
          description: x402 payment required
        "400":
          description: Invalid address or chain
  /v1/wallet/risk_score:
    post:
      operationId: walletRiskScore
      summary: Composite 0–100 risk score for an EVM wallet
      description: |
        $0.10/call. Returns a 0–100 composite risk score with risk_band
        (clean / low / medium / high / blocked) and itemized reasons per
        rule fired (OFAC SDN, known-mixer, contract anomaly).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [address]
              properties:
                address:
                  type: string
                  description: EVM address (0x… 20 bytes)
                  example: "0x8576aCC5C05D6Ce88f4e49bf65BdF0C62F91353C"
                chain:
                  type: string
                  description: ethereum | base | arbitrum | optimism | polygon (default ethereum)
                  example: ethereum
      responses:
        "200":
          description: Composite risk score with reasons
        "402":
          description: x402 payment required
        "400":
          description: Invalid address or chain
  /v1/labels/by_category:
    post:
      operationId: labelsByCategory
      summary: List addresses in bundled registries by category
      description: |
        $0.07/call. Returns all addresses in the bundled registries
        matching a category. Categories: sanctioned, mixer, exchange,
        dex, lending, stablecoin, wrapped-asset, founder, foundation,
        bridge, infrastructure.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [category]
              properties:
                category:
                  type: string
                  description: Category name
                  example: sanctioned
                limit:
                  type: number
                  description: Max results (1–200, default 50)
                  example: 50
      responses:
        "200":
          description: Category match list
        "402":
          description: x402 payment required
        "400":
          description: Missing category
components:
  securitySchemes:
    x402:
      type: http
      scheme: x402
      description: |
        Pay-per-call via x402 (USDC on Base). On first request, the API returns
        HTTP 402 with an "accepts" array. Sign and submit X-PAYMENT to retry.
security:
  - x402: []
