{
  "openapi": "3.1.0",
  "info": {
    "title": "x402 AI Agent API",
    "version": "1.0.0",
    "description": "Crypto research intelligence via REST and MCP.\n\n**Free endpoints** return market digests and token snapshots — no authentication needed.\n\n**Paid endpoints** use the [x402 protocol](https://x402.org) — HTTP-native USDC micropayments on Base. Payment IS authentication; no API keys required.\n\n## x402 Payment Flow\n\n1. Call a paid endpoint without a payment header → receive `402 Payment Required` with payment terms\n2. Sign an EIP-3009 USDC authorization on Base using the returned `accepts` requirements\n3. Retry the same request with the signed payment in an `X-Payment` header\n4. The facilitator verifies and settles the payment on-chain\n5. The endpoint executes and returns results\n\nUse [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch) to handle payment automatically.\n\n## MCP (Model Context Protocol)\n\nAI agents can connect to `https://www.obolai.xyz/mcp` via the [Model Context Protocol](https://modelcontextprotocol.io) for tool discovery and invocation.",
    "contact": {
      "name": "x402 AI Agent",
      "url": "https://github.com/aijayz/x402-ai-agent"
    },
    "license": {
      "name": "MIT",
      "url": "https://github.com/aijayz/x402-ai-agent/blob/main/LICENSE"
    }
  },
  "servers": [
    {
      "url": "https://www.obolai.xyz/api/v1",
      "description": "Production (Base mainnet)"
    }
  ],
  "tags": [
    { "name": "Digest", "description": "Daily market digest — free" },
    { "name": "Tokens", "description": "Token snapshots — free" },
    { "name": "Research", "description": "Paid research clusters via x402" }
  ],
  "paths": {
    "/digest/latest": {
      "get": {
        "operationId": "getLatestDigest",
        "tags": ["Digest"],
        "summary": "Get the latest daily digest",
        "description": "Returns the most recent AI-generated daily market digest with price data, whale signals, and sentiment for ~10 tokens.",
        "responses": {
          "200": {
            "description": "Latest digest",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DigestResponse" }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": { "type": "string", "example": "public, s-maxage=3600, stale-while-revalidate=1800" }
              }
            }
          },
          "404": {
            "description": "No digest available",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/digest/{date}": {
      "get": {
        "operationId": "getDigestByDate",
        "tags": ["Digest"],
        "summary": "Get digest for a specific date",
        "description": "Returns the daily market digest for the given date (YYYY-MM-DD format).",
        "parameters": [
          {
            "name": "date",
            "in": "path",
            "required": true,
            "description": "Date in YYYY-MM-DD format",
            "schema": { "type": "string", "format": "date", "example": "2026-03-29" }
          }
        ],
        "responses": {
          "200": {
            "description": "Digest for the requested date",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DigestResponse" }
              }
            }
          },
          "404": {
            "description": "No digest found for this date",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/tokens": {
      "get": {
        "operationId": "listTokens",
        "tags": ["Tokens"],
        "summary": "List tracked tokens",
        "description": "Returns the list of tokens covered by the daily digest, including 6 fixed majors and top movers.",
        "responses": {
          "200": {
            "description": "Token list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TokenListResponse" }
              }
            }
          }
        }
      }
    },
    "/tokens/{symbol}": {
      "get": {
        "operationId": "getTokenSnapshot",
        "tags": ["Tokens"],
        "summary": "Get token snapshot",
        "description": "Returns a snapshot of security, whale flow, sentiment, and unlock data for a tracked token.",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Token symbol (case-insensitive, e.g. BTC, ETH, SOL)",
            "schema": { "type": "string", "example": "ETH" }
          }
        ],
        "responses": {
          "200": {
            "description": "Token snapshot",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TokenSnapshotResponse" }
              }
            }
          },
          "404": {
            "description": "Token not found in current snapshot",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/research/defi-safety": {
      "post": {
        "operationId": "analyzeDefiSafety",
        "tags": ["Research"],
        "summary": "DeFi Safety Analysis",
        "description": "Analyze a token or contract for rug pull risks, honeypot detection, and vulnerabilities. Orchestrates 3 independent security services.",
        "x-x402-pricing": { "quick": "$0.05", "full": "$0.15" },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DefiSafetyInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Analysis results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DefiSafetyResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/research/whale-activity": {
      "post": {
        "operationId": "trackWhaleActivity",
        "tags": ["Research"],
        "summary": "Whale Activity Tracking",
        "description": "Track whale and smart money activity for a wallet or token address. Cross-references wallet risk, trade history, and on-chain whale flow.",
        "x-x402-pricing": { "estimate": "~$0.02" },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AddressInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Whale activity results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WhaleActivityResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/research/wallet-portfolio": {
      "post": {
        "operationId": "analyzeWalletPortfolio",
        "tags": ["Research"],
        "summary": "Wallet Portfolio Analysis",
        "description": "Deep-dive wallet analysis: risk profile, trade history, smart money tier, and 30-day PnL.",
        "x-x402-pricing": { "estimate": "~$0.02" },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AddressInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Portfolio analysis results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletPortfolioResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/research/social-narrative": {
      "post": {
        "operationId": "analyzeSocialNarrative",
        "tags": ["Research"],
        "summary": "Social Narrative Analysis",
        "description": "Analyze social narrative and market sentiment for a topic or address. Combines sentiment scoring with risk assessment.",
        "x-x402-pricing": { "estimate": "~$0.17" },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SocialNarrativeInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Social narrative results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SocialNarrativeResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/research/token-alpha": {
      "post": {
        "operationId": "screenTokenAlpha",
        "tags": ["Research"],
        "summary": "Token Alpha Screening",
        "description": "Screen a token for alpha signals: security score, unlock schedule, allocation breakdown, smart money moves, and token velocity.",
        "x-x402-pricing": { "estimate": "~$0.33" },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TokenAlphaInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token alpha results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenAlphaResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/research/market-trends": {
      "post": {
        "operationId": "analyzeMarketTrends",
        "tags": ["Research"],
        "summary": "Market Trends Analysis",
        "description": "Analyze market trends with sentiment, DEX volume, and stablecoin supply data.",
        "x-x402-pricing": { "estimate": "~$0.04" },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/MarketTrendsInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Market trend results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarketTrendsResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string", "example": "Missing required field: target" }
        }
      },
      "DigestResponse": {
        "type": "object",
        "required": ["date", "title", "content", "markers", "tokenCount", "generatedAt"],
        "properties": {
          "date": { "type": "string", "format": "date", "example": "2026-03-29" },
          "title": { "type": "string", "example": "Crypto Market Digest — March 29, 2026" },
          "content": { "type": "string", "description": "Markdown-formatted digest content" },
          "markers": {
            "oneOf": [
              { "type": "array", "items": {} },
              { "type": "null" }
            ],
            "description": "Token markers used in the digest"
          },
          "tokenCount": { "type": "integer", "example": 10 },
          "generatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "TokenListItem": {
        "type": "object",
        "required": ["symbol", "category"],
        "properties": {
          "symbol": { "type": "string", "example": "ETH" },
          "category": { "type": "string", "enum": ["fixed", "mover"], "description": "`fixed` = always-tracked major, `mover` = top gainer from CoinGecko top 100" }
        }
      },
      "TokenListResponse": {
        "type": "object",
        "required": ["tokens", "snapshotDate"],
        "properties": {
          "tokens": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/TokenListItem" }
          },
          "snapshotDate": { "type": "string", "format": "date" }
        }
      },
      "TokenSnapshotResponse": {
        "type": "object",
        "required": ["symbol", "name", "snapshotDate", "security", "whaleFlow", "sentiment", "unlocks"],
        "properties": {
          "symbol": { "type": "string", "example": "ETH" },
          "name": { "type": "string", "example": "Ethereum" },
          "snapshotDate": { "type": "string", "format": "date" },
          "security": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "score": { "type": "number", "example": 85 },
                  "details": { "type": "string" }
                },
                "required": ["score"]
              },
              { "type": "null" }
            ]
          },
          "whaleFlow": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "netFlowUsd": { "type": "number" },
                  "largeTxCount": { "type": "integer" },
                  "totalVolumeUsd": { "type": "number" }
                },
                "required": ["netFlowUsd", "largeTxCount"]
              },
              { "type": "null" }
            ]
          },
          "sentiment": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "score": { "oneOf": [{ "type": "number" }, { "type": "null" }] },
                  "label": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
                  "summary": { "oneOf": [{ "type": "string" }, { "type": "null" }] }
                }
              },
              { "type": "null" }
            ]
          },
          "unlocks": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "category": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
                  "sector": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
                  "projectedEndDate": { "oneOf": [{ "type": "string" }, { "type": "null" }] }
                }
              },
              { "type": "null" }
            ]
          }
        }
      },
      "ApiResponse": {
        "type": "object",
        "required": ["endpoint", "summary", "data", "costUsdc", "generatedAt"],
        "properties": {
          "endpoint": { "type": "string", "example": "defi-safety" },
          "summary": { "type": "string", "example": "Analyzed 0x... for DeFi safety risks." },
          "data": { "description": "Endpoint-specific result data" },
          "costUsdc": { "type": "number", "example": 0.11 },
          "generatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "ChainEnum": {
        "type": "string",
        "enum": ["base", "ethereum", "arbitrum", "optimism"],
        "default": "ethereum"
      },
      "DefiSafetyInput": {
        "type": "object",
        "required": ["target"],
        "properties": {
          "target": { "type": "string", "description": "Token address, contract address, or token name", "example": "0x7Fc66500c84A76Ad7e9c93437bFc5Ac33E2DDaE9" },
          "depth": { "type": "string", "enum": ["quick", "full"], "default": "quick", "description": "`quick` ($0.05) or `full` ($0.15)" },
          "chain": { "$ref": "#/components/schemas/ChainEnum" }
        }
      },
      "DefiSafetyData": {
        "type": "object",
        "properties": {
          "security": { "description": "Security scan results" },
          "riskAssessment": { "description": "Contract risk assessment" },
          "tokenUnlocks": { "description": "Upcoming token unlock schedule" },
          "onChain": {
            "type": "object",
            "properties": {
              "liquidationRisk": { "description": "DeFi liquidation risk metrics" },
              "dexDepth": { "description": "DEX liquidity depth analysis" }
            }
          }
        }
      },
      "DefiSafetyResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/ApiResponse" },
          { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DefiSafetyData" } } }
        ]
      },
      "AddressInput": {
        "type": "object",
        "required": ["address"],
        "properties": {
          "address": { "type": "string", "description": "EVM address (0x + 40 hex chars)", "pattern": "^0x[a-fA-F0-9]{40}$", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
          "chain": { "$ref": "#/components/schemas/ChainEnum" }
        }
      },
      "WhaleActivityData": {
        "type": "object",
        "properties": {
          "walletRisk": { "description": "Wallet risk score and flags" },
          "whaleMovements": { "description": "Recent large holder movements" },
          "recentTrades": { "description": "Recent trade history" },
          "onChain": {
            "type": "object",
            "properties": {
              "whaleFlow": { "description": "Net whale flow data" },
              "smartMoney": { "description": "Smart money accumulation signals" }
            }
          }
        }
      },
      "WhaleActivityResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/ApiResponse" },
          { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WhaleActivityData" } } }
        ]
      },
      "WalletPortfolioData": {
        "type": "object",
        "properties": {
          "walletRisk": { "description": "Wallet risk profile" },
          "whaleMovements": { "description": "Whale tier classification" },
          "recentTrades": { "description": "Recent trade history" },
          "onChain": {
            "type": "object",
            "properties": {
              "pnl30d": { "description": "30-day profit & loss breakdown" }
            }
          }
        }
      },
      "WalletPortfolioResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/ApiResponse" },
          { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WalletPortfolioData" } } }
        ]
      },
      "SocialNarrativeInput": {
        "type": "object",
        "required": ["topic"],
        "properties": {
          "topic": { "type": "string", "description": "Free text query or EVM address", "example": "ethereum merge" },
          "chain": { "$ref": "#/components/schemas/ChainEnum" }
        }
      },
      "SocialNarrativeData": {
        "type": "object",
        "properties": {
          "sentiment": { "description": "Sentiment score and breakdown" },
          "riskAssessment": { "description": "Narrative risk assessment" }
        }
      },
      "SocialNarrativeResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/ApiResponse" },
          { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SocialNarrativeData" } } }
        ]
      },
      "TokenAlphaInput": {
        "type": "object",
        "required": ["target"],
        "properties": {
          "target": { "type": "string", "description": "Token name, symbol, or contract address", "example": "AAVE" },
          "chain": { "$ref": "#/components/schemas/ChainEnum" }
        }
      },
      "TokenAlphaData": {
        "type": "object",
        "properties": {
          "security": { "description": "Token security score" },
          "tokenomics": {
            "type": "object",
            "properties": {
              "unlocks": { "description": "Token unlock schedule" },
              "allocations": { "description": "Token allocation breakdown" }
            }
          },
          "onChain": {
            "type": "object",
            "properties": {
              "smartMoney": { "description": "Smart money activity" },
              "velocity": { "description": "Token velocity metrics" }
            }
          }
        }
      },
      "TokenAlphaResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/ApiResponse" },
          { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TokenAlphaData" } } }
        ]
      },
      "MarketTrendsInput": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": { "type": "string", "description": "Market trend query", "example": "DeFi lending rates" },
          "contractAddress": { "type": "string", "description": "Optional contract address for audit" },
          "chain": { "$ref": "#/components/schemas/ChainEnum" }
        }
      },
      "MarketTrendsData": {
        "type": "object",
        "properties": {
          "sentiment": { "description": "Market sentiment analysis" },
          "onChain": {
            "type": "object",
            "properties": {
              "dexVolume": { "description": "7-day DEX volume data" },
              "stablecoinSupply": { "description": "Stablecoin supply trends" }
            }
          }
        }
      },
      "MarketTrendsResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/ApiResponse" },
          { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MarketTrendsData" } } }
        ]
      },
      "X402PaymentRequired": {
        "type": "object",
        "required": ["x402Version", "error", "accepts"],
        "properties": {
          "x402Version": { "type": "integer", "example": 1 },
          "error": { "type": "string", "example": "Payment required" },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scheme": { "type": "string", "example": "exact" },
                "network": { "type": "string", "example": "base" },
                "maxAmountRequired": { "type": "string", "description": "Amount in USDC base units (6 decimals)", "example": "50000" },
                "payTo": { "type": "string", "description": "Seller wallet address" },
                "asset": { "type": "string", "description": "USDC contract address on Base", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
                "maxTimeoutSeconds": { "type": "integer", "example": 300 },
                "resource": { "type": "string", "example": "/api/v1/research/defi-safety" },
                "mimeType": { "type": "string", "example": "application/json" },
                "description": { "type": "string", "example": "DeFi Safety Analysis" }
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request body",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "PaymentRequired": {
        "description": "x402 payment required — returns payment terms for USDC on Base",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/X402PaymentRequired" }
          }
        }
      },
      "InternalError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      }
    }
  }
}