predictive_behaviour¶

Profiles a wallet's complete on-chain history and predicts what it is likely to do next. Powers AI agent personalisation, user segmentation, next-best-action recommendations, and experience-level scoring.

This is the core tool for personalising DeFi agents — giving them real behavioural context about each wallet they interact with, rather than serving generic responses.

MCP Endpoint: https://prediction.mcp.chainaware.ai/sse

---

Supported Networks¶

---

Input Schema¶

---

Output Schema¶

{
  "message": "string",
  "walletAddress": "string",
  "status": "Fraud | Not Fraud | New Address",
  "probabilityFraud": "0.00–1.00",
  "lastChecked": "ISO-8601 timestamp",
  "forensic_details": { },
  "categories": [
    { "Category": "DeFi Lender", "Count": 142 },
    { "Category": "Bridge User", "Count": 38 }
  ],
  "riskProfile": [
    { "Category": "Conservative", "Balance_age": 1.8 }
  ],
  "segmentInfo": "JSON-string of segment counts",
  "experience": { "Type": "Experience", "Value": 87 },
  "intention": {
    "Type": "Intentions",
    "Value": {
      "Prob_Trade": "High",
      "Prob_Stake": "Medium",
      "Prob_Bridge": "Low",
      "Prob_NFT_Buy": "Low"
    }
  },
  "protocols": [
    { "Protocol": "Aave", "Count": 54 },
    { "Protocol": "Uniswap", "Count": 31 }
  ],
  "recommendation": {
    "Type": "Recommendation",
    "Value": [
      "Consider showcasing high-yield staking opportunities",
      "This wallet has strong DeFi experience — skip onboarding prompts"
    ]
  },
  "createdAt": "ISO-8601 timestamp",
  "updatedAt": "ISO-8601 timestamp"
}

---

Key Output Fields Explained¶

categories — Behavioural Segments¶

Classifies the wallet's primary on-chain activity patterns by type and frequency:

intention — Predicted Next Actions¶

Probability of the wallet's next on-chain action in the near term:

experience — Expertise Score¶

Integer 0–100 representing on-chain maturity:

recommendation — Personalised Action Suggestions¶

Array of strings the agent can use directly to shape its response or UI. For example: skip onboarding for expert wallets, surface staking CTAs for high-stake-intent users, show beginner guides for low-experience wallets.

protocols — Protocol Usage History¶

Ordered list of protocols this wallet has interacted with, with interaction counts. Use this to tailor messaging to a wallet's existing DeFi context — e.g. if they use Aave heavily, lead with lending-related content.

---

Code Examples¶

Node.js — Personalisation Pattern¶

const profile = await client.callTool({
  name: "predictive_behaviour",
  arguments: {
    apiKey: process.env.CHAINAWARE_API_KEY,
    network: "ETH",
    walletAddress: userWallet
  }
});

const { intention, experience, recommendation } = profile;

// Route based on experience
if (experience.Value > 75) {
  agent.skipOnboarding();
  agent.showAdvancedFeatures();
} else {
  agent.showBeginnersGuide();
}

// Surface intent-matched CTAs
if (intention.Value.Prob_Stake === "High") {
  agent.highlightStakingOpportunities();
}

// Use recommendations directly in agent context
agent.setContext(recommendation.Value.join("\n"));

Python¶

result = await session.call_tool("predictive_behaviour", {
    "apiKey": os.environ["CHAINAWARE_API_KEY"],
    "network": "ETH",
    "walletAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
})

experience = result["experience"]["Value"]        # e.g. 87
intentions = result["intention"]["Value"]         # dict of probabilities
categories = result["categories"]                 # list of {Category, Count}
recommendations = result["recommendation"]["Value"]  # list of strings

Example Agent Prompts¶

"What will 0xABC123... on ETH do next?"
"Is this user a DeFi lender or an NFT trader?"
"What's the experience level of this Solana wallet?"
"Recommend the best yield strategy for 0x123... on BASE."
"Personalise my DeFi agent's response for this wallet."
"Should I show the beginner onboarding flow to 0x789...?"
"Which protocols does this wallet use most on BNB?"
"Segment this wallet for my marketing campaign."

---

Use Cases¶

• Personalised onboarding — route wallets to beginner, intermediate, or advanced flows based on experience
• Dynamic UI — show advanced features to expert wallets; hide complexity from newcomers
• Intent-matched CTAs — show staking CTAs to high-stake-intent wallets; show trading features to high-trade-intent wallets
• Targeted campaigns — segment wallets by categories (NFT, DeFi, Bridge) for precision marketing
• Lending decisions — assess borrower experience and risk tolerance before setting loan terms
• Airdrop strategy — identify and prioritise high-experience wallets in reward distribution
• GameFi personalisation — adapt in-game economies based on a player wallet's on-chain spending patterns

---

Error Codes¶

---

Related Tools¶

• predictive_fraud — always pair with this for a complete safety + profile picture; predictive_behaviour also returns probabilityFraud but predictive_fraud provides deeper forensic detail
• token_rank_single — call predictive_behaviour on a token's top holders to assess the quality of its community

---

Further Reading¶

• Web3 Behavioral User Analytics Guide — using predictive_behaviour for analytics and segmentation
• Why Personalization Is the Next Big Thing for AI Agents
• DeFi Onboarding in 2026: Why 90% of Connected Wallets Never Transact

---

See also: Prediction MCP Overview | predictive_fraud | predictive_rug_pull