{
  "openapi": "3.1.0",
  "info": {
    "title": "address-intel",
    "version": "1.0.0",
    "description": "Multichain EVM wallet reputation scoring for AI agents. Returns a 0-100 trust score, verdict, and per-chain signals for any wallet across Base, Ethereum, Arbitrum, Optimism, and Polygon. The /score endpoint is x402-gated (pay-per-call in USDC on Base, no signup, no API key). Payments are verified and settled through the Coinbase CDP x402 facilitator.",
    "contact": {
      "name": "3AI New Zealand",
      "url": "https://address-intel.3ainewzealand.workers.dev",
      "email": "3ainewzealand@gmail.com"
    },
    "license": {
      "name": "Proprietary"
    },
    "x-guidance": "Counterparty wallet risk check before your agent sends funds: OFAC sanctions / phishing / exploiter flag + 0-100 multichain trust score + a machine decision (proceed/caution/block) in ONE $0.005 call. GET /score/{address} with any 0x EVM address — pay $0.005 USDC on Base via x402 (signed EIP-3009 authorization; no signup, no API key). Returns ofac_flag, recommendation (proceed|caution|block), score, verdict (established/active/emerging/new/dormant_or_unknown/contract/flagged), and per-chain activity signals across Base, Ethereum, Arbitrum, Optimism, and Polygon — 5 chains in one call instead of querying 5 explorers. AML/KYT-style pre-send screening for trading bots, treasury agents, payment routers and x402 buyers. Decision rule: block if ofac_flag or recommendation=block; reduce size on caution. Free teaser: GET /preflight/{address} (danger-list check only, JSON, no payment). Free human HTML report: GET /report/{address}. Deep risk dossier with plain-English rationale: GET /dossier/{address} ($0.25)."
  },
  "servers": [
    {
      "url": "https://address-intel.3ainewzealand.workers.dev"
    }
  ],
  "x-x402": {
    "version": 2,
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xa29cf767dd782de5409e2af8600bc3a18e5ca6de",
    "facilitator": "cdp"
  },
  "paths": {
    "/v1/dossier/{address}": {
      "get": {
        "operationId": "getDossier",
        "summary": "Full counterparty dossier (paid, x402)",
        "description": "Entity attribution with confidence, structural vs intelligence cluster tiers, OFAC sanctions screening, Travel-Rule indicators, EIP-7702 delegation detection, tags/categories, 17-chain coverage and full source provenance. Returns 402 with x402 payment requirements when unpaid.",
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dossier",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "schema": "address-intel.dossier/v1",
                  "address": "0x28c6c06298d514db089934071355e5743bf21d60",
                  "entity": {
                    "matched": true,
                    "name": "Binance",
                    "type": "exchange",
                    "confidence": 0.95
                  },
                  "risk": {
                    "reputation_score": 100,
                    "risk_score": 0,
                    "risk_level": "low",
                    "recommendation": "PROCEED"
                  },
                  "cluster": {
                    "structural": {
                      "confidence": 1,
                      "chains": [
                        "base",
                        "ethereum"
                      ]
                    },
                    "intelligence": {
                      "available": true,
                      "confidence": 0.95
                    }
                  },
                  "sanctions": {
                    "match": false,
                    "screened_lists": [
                      "OFAC_SDN_ETH"
                    ]
                  },
                  "travel_rule": {
                    "vasp_attributed": true,
                    "determination": null
                  },
                  "coverage": {
                    "chains_requested": 17,
                    "chains_answered": 16
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid address"
          },
          "402": {
            "description": "Payment required (x402). Pay 0.10 USDC on Base and retry with X-PAYMENT."
          }
        },
        "x-x402": {
          "price": "0.10",
          "asset": "USDC",
          "network": "eip155:8453",
          "payTo": "0xa29cf767dd782de5409e2af8600bc3a18e5ca6de"
        }
      }
    },
    "/v1/safety/{address}": {
      "get": {
        "operationId": "getSafety",
        "summary": "Fast pre-flight safety check (paid, x402)",
        "description": "Cheap gate before a transfer: OFAC sanctions match, danger-list exposure, sybil indicators, EIP-7702 delegation, 0-100 risk and reputation scores across Base and Ethereum.",
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Safety result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "schema": "address-intel.safety/v1",
                  "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
                  "reputation_score": 100,
                  "risk_score": 0,
                  "risk_level": "low",
                  "verdict": "established",
                  "recommendation": "PROCEED",
                  "blocked": false,
                  "signals": {
                    "sanctions_match": false,
                    "danger_list_match": false,
                    "active_chains": 2,
                    "total_outbound_tx": 6020
                  },
                  "sanctions": {
                    "match": false,
                    "screened_lists": [
                      "OFAC_SDN_ETH"
                    ]
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required (x402). Pay 0.002 USDC on Base and retry with X-PAYMENT."
          }
        },
        "x-x402": {
          "price": "0.002",
          "asset": "USDC",
          "network": "eip155:8453",
          "payTo": "0xa29cf767dd782de5409e2af8600bc3a18e5ca6de"
        }
      }
    },
    "/v1/coverage": {
      "get": {
        "operationId": "getCoverage",
        "summary": "Coverage + freshness (free)",
        "responses": {
          "200": {
            "description": "Chains covered, sanctions list freshness, known gaps"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcpRpc",
        "summary": "MCP JSON-RPC endpoint (streamable-http)",
        "description": "MCP server. Supports initialize, tools/list, tools/call. Tools: address_preflight (free), address_safety_check, address_dossier.",
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response"
          }
        }
      }
    },
    "/score/{address}": {
      "get": {
        "operationId": "scoreWallet",
        "summary": "Score a wallet (paid)",
        "description": "Returns a 0-100 multichain reputation score, a verdict, and per-chain signals for the given EVM address. Payment required via x402: send a signed EIP-3009 USDC authorization. Without payment, responds 402 with payment requirements in the PAYMENT-REQUIRED header.",
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "description": "0x-prefixed EVM address (40 hex chars) to score.",
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          }
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.005"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Wallet reputation score.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScoreResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid address."
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    },
    "/dossier/{address}": {
      "get": {
        "operationId": "dossierWallet",
        "summary": "Deep wallet risk dossier (paid, $0.25 USDC via x402)",
        "description": "Everything in /score plus a plain-English risk rationale for the verdict. One-call counterparty due diligence before an agent moves size. Pay $0.25 USDC on Base via x402 (signed EIP-3009 authorization; no signup, no API key).",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          }
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.25"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Deep risk dossier: score result plus plain-English rationale.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScoreResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid address."
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    },
    "/report/{address}": {
      "get": {
        "operationId": "reportWallet",
        "summary": "Public HTML trust report (free)",
        "description": "Free, human-readable, shareable HTML trust report for any EVM address. Same scoring as /score, rendered as a web page. No payment.",
        "security": [],
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML report.",
            "content": {
              "text/html": {}
            }
          },
          "400": {
            "description": "Invalid address."
          }
        }
      }
    },
    "/": {
      "get": {
        "operationId": "serviceInfo",
        "summary": "Service info (free)",
        "security": [],
        "responses": {
          "200": {
            "description": "Service metadata + endpoint list.",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "health",
        "summary": "Liveness (free)",
        "security": [],
        "responses": {
          "200": {
            "description": "OK."
          }
        }
      }
    },
    "/.well-known/x402": {
      "get": {
        "operationId": "x402Discovery",
        "summary": "x402 discovery doc (free)",
        "security": [],
        "responses": {
          "200": {
            "description": "Machine-readable x402 resource + payment metadata.",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/.well-known/agent.json": {
      "get": {
        "operationId": "agentCard",
        "summary": "A2A agent card (free)",
        "security": [],
        "responses": {
          "200": {
            "description": "Google A2A agent card.",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/.well-known/mcp.json": {
      "get": {
        "operationId": "mcpDoc",
        "summary": "MCP discovery doc (free)",
        "security": [],
        "responses": {
          "200": {
            "description": "MCP tool definition.",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "openapiSpec",
        "summary": "This OpenAPI document (free)",
        "security": [],
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 spec.",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "http",
        "scheme": "x402",
        "description": "x402 micropayment. Send a signed EIP-3009 USDC (Base) transfer authorization. Price: 0.005 USDC per call."
      },
      "siwx": {
        "type": "http",
        "scheme": "siwx",
        "description": "Sign-In With X (wallet signature) identity authentication for identity-gated (non-paid) routes."
      }
    },
    "schemas": {
      "ScoreResult": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "verdict": {
            "type": "string",
            "enum": [
              "established",
              "active",
              "emerging",
              "new",
              "dormant_or_unknown",
              "contract",
              "flagged"
            ]
          },
          "ofac_flag": {
            "type": "boolean",
            "description": "true if the address is OFAC-sanctioned / on a sanctions list"
          },
          "recommendation": {
            "type": "string",
            "enum": [
              "proceed",
              "caution",
              "block"
            ],
            "description": "machine decision for the agent"
          },
          "signals": {
            "type": "object",
            "properties": {
              "account_age_days": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "active_chains": {
                "type": "integer"
              },
              "total_outbound_tx": {
                "type": "integer"
              },
              "has_balance": {
                "type": "boolean"
              },
              "is_contract": {
                "type": "boolean"
              }
            }
          },
          "chains": {
            "type": "object",
            "description": "Per-chain presence keyed by chain name (base, ethereum, arbitrum, optimism, polygon)."
          },
          "meta": {
            "type": "object"
          }
        },
        "required": [
          "address",
          "score",
          "verdict",
          "signals",
          "chains"
        ]
      },
      "PaymentRequired": {
        "type": "object",
        "properties": {
          "x402Version": {
            "type": "integer",
            "example": 2
          },
          "error": {
            "type": "string",
            "example": "X-PAYMENT header is required"
          },
          "resource": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "mimeType": {
                "type": "string"
              }
            }
          },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "extensions": {
            "type": "object"
          }
        }
      }
    }
  }
}