AI Insights API

AI-powered token analysis and portfolio report generation endpoints.

Get Token Insights

Generate an AI analysis for a specific token including price trends, market signals, risks, and outlook.

Request

POST /ai-insights

Body Parameters

Parameter	Type	Required	Description
tokenName	string	Yes	Name of the token (e.g., "Ethereum")
tokenAddress	string	Yes	Contract address of the token
chainId	number	Yes	Chain ID where the token exists
riskLevel	string	No	Risk profile: conservative, balanced, or aggressive. Defaults to balanced

Example Request

{
  "tokenName": "Ethereum",
  "tokenAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "chainId": 1,
  "riskLevel": "balanced"
}

Response

{
  "tokenName": "Ethereum",
  "tokenAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "chainId": 1,
  "report": "## 1. Current Price Trend\n\nETH is trading at $3,450 with bullish momentum...",
  "generatedAt": "2026-03-27T14:30:00.000Z"
}

Field	Type	Description
tokenName	string	Token name
tokenAddress	string	Token contract address
chainId	number	Chain ID
report	string	AI-generated markdown analysis (~120 words)
generatedAt	string	ISO 8601 timestamp of generation

---

Get Portfolio Report

Generate an AI portfolio analysis with allocation recommendations tailored to the user's risk profile.

Request

POST /ai-insights/portfolio-report

Body Parameters

Parameter	Type	Required	Description
userAddress	string	Yes	User's wallet address
chainId	number	Yes	Chain ID to analyze. Use -1 for all chains
riskLevel	string	No	Risk profile: conservative, balanced, or aggressive. Defaults to balanced

Example Request

{
  "userAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "chainId": -1,
  "riskLevel": "aggressive"
}

Response

{
  "output": {
    "portfolio_summary": "Your portfolio is heavily concentrated in large-cap assets with 65% in ETH and 20% in BTC...",
    "portfolio_allocation": [
      {
        "asset_name": "Ethereum (ETH)",
        "current_allocation": 65,
        "bias": "bullish",
        "key_factor": "Strong network activity and institutional inflows",
        "suggested_allocation": 55,
        "suggested_action": "reduce"
      },
      {
        "asset_name": "Bitcoin (BTC)",
        "current_allocation": 20,
        "bias": "bullish",
        "key_factor": "ETF inflows and halving cycle momentum",
        "suggested_allocation": 25,
        "suggested_action": "accumulate"
      }
    ],
    "portfolio_analysis": [
      "High concentration risk with 85% in two assets — consider diversifying into mid-cap DeFi tokens",
      "No stablecoin allocation reduces downside protection during market corrections",
      "Current macro environment favors gradual rebalancing over aggressive changes"
    ]
  },
  "generatedAt": "2026-03-27T14:35:00.000Z",
  "chainId": -1
}

Response Fields

Field	Type	Description
output.portfolio_summary	string	Overview of portfolio composition
output.portfolio_allocation	array	Per-asset analysis and recommendations
output.portfolio_allocation[].asset_name	string	Asset name and symbol
output.portfolio_allocation[].current_allocation	number	Current allocation percentage
output.portfolio_allocation[].bias	string	bullish, neutral, or bearish
output.portfolio_allocation[].key_factor	string	Primary factor supporting the bias
output.portfolio_allocation[].suggested_allocation	number	Recommended allocation percentage
output.portfolio_allocation[].suggested_action	string	accumulate, hold, or reduce
output.portfolio_analysis	array	List of analysis points covering risk, diversification, and strategy
generatedAt	string	ISO 8601 timestamp
chainId	number	Chain ID used for analysis

---

Error Responses

Status	Description
400	Invalid parameters (unsupported chain ID, missing required fields)
404	No token balances found for the given address (portfolio report)
503	AI provider unavailable