{
  "openapi": "3.1.0",
  "info": {
    "title": "Base Wallet Activity and Due-Diligence API",
    "version": "1.0.0",
    "contact": {
      "name": "Base Wallet Profile API Support",
      "email": "kriprose@yandex.ru"
    },
    "description": "Optional Base wallet context for counterparty research before payment: native balance, wallet age, transaction and token-transfer counts, activity dates when indexed, contract status, and heuristic activity fields. The fixed-path agent route costs 0.005 USDC; the standard route costs 0.01 USDC on Base Mainnet. Not identity verification, sanctions screening, or a safety guarantee.",
    "x-samples-url": "https://x402-wallet-profile-api-production.up.railway.app/samples.json",
    "x-guidance": "Use when an app or agent needs public on-chain context for Base wallet due diligence or counterparty research: wallet activity, transaction counts, token-transfer counts, wallet age and activity dates when indexed. Use GET /wallet/{address} for $0.01 USDC or the fixed-path GET /wallet?address={address} for $0.005 USDC; both use Base Mainnet. Pay the exact x402 amount in the challenge and retry the same request. Treat activityScore, verdict, and riskFlags as heuristic signals, not sanctions screening, identity verification, or a safety guarantee.",
    "externalDocs": {
      "description": "Service overview and x402 usage",
      "url": "https://x402-wallet-profile-api-production.up.railway.app/"
    }
  },
  "servers": [{ "url": "https://x402-wallet-profile-api-production.up.railway.app" }],
  "paths": {
    "/wallet": {
      "get": {
        "operationId": "getBaseWalletProfileByQuery",
        "summary": "Base wallet age and activity profile for counterparty research",
        "description": "Optional Base wallet context before paying or accepting payment from a counterparty. Pass an EVM address as the address query parameter. Returns native balance, transaction and ERC-20 transfer counts, first and last activity when indexed, contract status, and heuristic activity fields. Not identity or sanctions screening and not a safety guarantee.",
        "tags": ["Base", "Wallet Activity", "Wallet Age", "Counterparty Research", "Token Transfers"],
        "x-payment-info": {
          "protocols": ["x402"],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.005" },
          "network": "eip155:8453",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "payTo": "0x801Bc709726148CA257Ae37156fc0Bc74e52B72c"
        },
        "parameters": [{
          "name": "address", "in": "query", "required": true,
          "description": "20-byte EVM address to analyze on Base.",
          "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" },
          "example": "0x0000000000000000000000000000000000000001"
        }],
        "responses": {
          "200": {
            "description": "Same wallet profile contract as GET /wallet/{address}.",
            "headers": {
              "X-Profile-Scope": { "$ref": "#/components/headers/ProfileScope" },
              "X-Profile-Limitations": { "$ref": "#/components/headers/ProfileLimitations" }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletProfile" } } }
          },
          "400": { "description": "Invalid or missing EVM address." },
          "402": {
            "description": "x402 payment required; see PAYMENT-REQUIRED header.",
            "headers": {
              "X-Profile-Scope": { "$ref": "#/components/headers/ProfileScope" },
              "X-Profile-Limitations": { "$ref": "#/components/headers/ProfileLimitations" }
            }
          },
          "502": { "description": "Base RPC unavailable." },
          "504": { "description": "Request deadline exceeded." }
        }
      }
    },
    "/wallet/{address}": {
      "get": {
        "operationId": "getBaseWalletProfile",
        "summary": "Base wallet age and activity profile for counterparty research",
        "description": "Optional Base wallet context before paying or accepting payment from a counterparty. Returns native balance, transaction and ERC-20 transfer counts, first and last activity when indexed, contract status, and heuristic activity fields. Public-chain context only; not identity or sanctions screening and not a safety guarantee. This route costs 0.01 USDC on Base Mainnet.",
        "tags": ["Base", "Wallet Activity", "Wallet Age", "Counterparty Research", "Token Transfers"],
        "x-payment-info": {
          "protocols": ["x402"],
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" },
          "network": "eip155:8453",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "payTo": "0x801Bc709726148CA257Ae37156fc0Bc74e52B72c"
        },
        "parameters": [{
          "name": "address", "in": "path", "required": true,
          "description": "20-byte EVM address to analyze on Base.",
          "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "default": "0x0000000000000000000000000000000000000001" },
          "example": "0x0000000000000000000000000000000000000001"
        }],
        "responses": {
          "200": {
            "description": "Wallet profile. Enrichment fields may be null when complete history is unavailable.",
            "headers": {
              "X-Profile-Scope": { "$ref": "#/components/headers/ProfileScope" },
              "X-Profile-Limitations": { "$ref": "#/components/headers/ProfileLimitations" }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletProfile" } } }
          },
          "400": { "description": "Invalid EVM address." },
          "402": {
            "description": "x402 payment required; see PAYMENT-REQUIRED header.",
            "headers": {
              "X-Profile-Scope": { "$ref": "#/components/headers/ProfileScope" },
              "X-Profile-Limitations": { "$ref": "#/components/headers/ProfileLimitations" }
            }
          },
          "502": { "description": "Base RPC unavailable." },
          "504": { "description": "Request deadline exceeded." }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "WalletProfile": {
        "type": "object",
        "required": ["address", "chain", "generatedAt", "isContract", "balanceEth", "outgoingTxCount", "totalTxCount", "tokenTransfers", "firstSeen", "lastSeen", "ageDays", "label", "activityScore", "verdict", "riskFlags", "dataSources"],
        "properties": {
          "address": { "type": "string" },
          "chain": { "type": "string", "const": "base" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "isContract": { "type": "boolean" },
          "balanceEth": { "type": "string", "description": "Native Base ETH balance, expressed in ETH." },
          "outgoingTxCount": { "type": "integer", "minimum": 0 },
          "totalTxCount": { "type": "integer", "minimum": 0, "description": "Count may be incomplete when riskFlags contains total_tx_count_incomplete." },
          "tokenTransfers": { "type": ["integer", "null"], "minimum": 0 },
          "firstSeen": { "type": ["string", "null"], "format": "date-time" },
          "lastSeen": { "type": ["string", "null"], "format": "date-time" },
          "ageDays": { "type": ["integer", "null"], "minimum": 0 },
          "label": { "type": ["string", "null"] },
          "activityScore": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Heuristic public activity signal only; not a safety verdict." },
          "verdict": { "type": "string", "description": "Activity category only; not a safety, sanctions, theft, or identity verdict.", "enum": ["empty", "contract", "new_wallet", "low_activity", "active_retail", "active_high", "whale"] },
          "riskFlags": { "type": "array", "description": "Heuristic activity/coverage flags only. An empty array does not mean the wallet is safe.", "items": { "type": "string" } },
          "dataSources": { "type": "array", "items": { "type": "string" } }
        }
      }
    },
    "headers": {
      "ProfileScope": {
        "description": "This response contains public on-chain activity context only.",
        "schema": { "type": "string", "enum": ["public-onchain-activity-only"] }
      },
      "ProfileLimitations": {
        "description": "Comma-separated machine-readable limitations. An empty riskFlags array does not mean that a wallet is safe; activityScore is heuristic; sanctions, theft, and identity screening are not performed.",
        "schema": {
          "type": "string",
          "example": "no-sanctions-screening, no-theft-screening, no-identity-verification, no-safety-verdict, empty-riskFlags-do-not-imply-safety, activityScore-is-heuristic"
        }
      }
    }
  }
}