AI-powered tools to analyze wallet behaviour prediction,fraud detection and rug pull prediction.
🧠 ChainAware Behavioural Prediction MCP Server
MCP Server Name: ChainAware Behavioural Prediction MCP
Category: Web3 / Security / DeFi Analytics
Status: Public tools – Private backend
Access: By request (API key · x402 payment supported)
Server URL: [https://prediction.mcp.chainaware.ai/sse]
Repository: [https://github.com/ChainAware/behavioral-prediction-mcp]
Website: [https://chainaware.ai/]
Twitter: [https://x.com/ChainAware/]
LinkedIn: [https://www.linkedin.com/company/chainaware]
Blog: [https://chainaware.ai/blog]
Learn: [https://chainaware.ai/learn]
Examples: [https://github.com/ChainAware/examples]
Featured in: CB Insights Fraud Prevention Market Map for the AI Era — ChainAware recognised as a leading AI-era fraud prevention solution for Web3 (2026).
Listed on: BNB Chain AI Landscape — ChainAware listed by BNB Chain as a key AI project in the ecosystem (2025).
Listed on: BNB Chain Kickstart — Marketing Tools — ChainAware's Growth Agents and Wallet Marketer featured in the BNB Chain Kickstart programme's Marketing Tools section (2025).
Awarded: Google Cloud $250k Grant — ChainAware selected for a $250,000 Google Cloud grant (2025).
Selected for: AWS Fintech Accelerator — ChainAware accepted into the AWS Fintech Accelerator programme (2024).
Listed on: Safary Club Web3 Growth Landscape — Growth Tools — ChainAware featured in the Growth Tools for Web3 Projects category (2024).
mcp-name: io.github.ChainAware/chainaware-behavioral-prediction-mcp
📖 Description
The Behavioural Prediction MCP Server provides AI-powered tools to analyze wallet behaviour prediction,fraud detection and rug pull prediction.
Developers and platforms can integrate these tools through the MCP protocol to safeguard DeFi users, monitor liquidity risks, and score wallet or contract trustworthiness.
All tools follow the Model Context Protocol (MCP) and can be consumed via MCP-compatible clients.
Backtesting verified: 98% Predictive Fraud Detection accuracy · 90.1% Rug Pull Detection accuracy
🏆 ChainAware is featured in the CB Insights Fraud Prevention Market Map for the AI Era — recognised as a leading AI-powered fraud prevention solution for Web3 (2026).
🌐 ChainAware is listed on the BNB Chain AI Landscape — recognised as a key AI project in the BNB Chain ecosystem (2025).
🚀 ChainAware is listed on BNB Chain Kickstart — Marketing Tools — Growth Agents and Wallet Marketer featured in BNB Chain's official programme for ecosystem growth (2025).
💰 ChainAware received a $250k Google Cloud Grant — selected by Google Cloud for infrastructure and AI development (2025).
☁️ ChainAware was accepted into the AWS Fintech Accelerator — selected by AWS for its Fintech Accelerator programme (2024).
🌱 ChainAware is featured in the Safary Club Web3 Growth Landscape — Growth Tools — listed in the Growth Tools for Web3 Projects category (2024).
⚙️ Available Tools
1. Predictive Fraud Detection Tool
ID: predictive_fraud
Description: This AI‑powered algorithm forecasts the likelihood of fraudulent activity on a given wallet address before it happens (≈98% backtesting accuracy), and performs AML/Anti‑Money‑Laundering checks. Use this when your user wants a risk assessment or early‑warning on a blockchain address.
➡️ Example Use Cases:
• Is it safe to intercant with vitalik.eth ? • What is the fraudulent status of this address ? • Is my new wallet at risk of being used for fraud?
Inputs:
| Name | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------------- | | apiKey | string | ✅* | ChainAware API key — or omit when using x402 payments | | network | string | ✅ | Blockchain network (ETH, BNB,POLYGON,TON,BASE, TRON, HAQQ) | | walletAddress | string | ✅ | The wallet address to evaluate |
Outputs (JSON):
{
"message": "string", // e.g. “Success” or error description
"walletAddress": "string", // blockchain wallet address that was analyzed
"chain": "string", // blockchain network identifier (e.g. ETH, BNB,POLYGON,TON,BASE, TRON, HAQQ)
"status": "string", // classification result (e.g. “Fraud” | “Not Fraud” | “New Address”)
"probabilityFraud": "0.00–1.00", // decimal fraud probability score (string to preserve precision)
"token": "string | null", // optional token associated with the check (may be null)
"lastChecked": "ISO-8601 timestamp", // last time the wallet risk analysis was executed
"forensic_details": {
"cybercrime": "string", // indicator score for cybercrime activity
"money_laundering": "string", // indicator score for money laundering activity
"numberofmaliciouscontractscreated": "string", // number of malicious contracts deployed by this wallet
"gas_abuse": "string", // gas abuse indicator
"financial_crime": "string", // financial crime indicator
"darkweb_transactions": "string", // interaction with darkweb-linked wallets
"reinit": "string", // reinitialization exploit indicator
"phishing_activities": "string", // phishing activity indicator
"fake_kyc": "string", // fake KYC related activity
"blacklist_doubt": "string", // suspected blacklist association
"fakestandardinterface": "string", // fake ERC interface indicator
"data_source": "string", // source of forensic intelligence (may be empty)
"stealing_attack": "string", // stealing attack indicator
"blackmail_activities": "string", // blackmail activity indicator
"sanctioned": "string", // sanction exposure indicator
"maliciousminingactivities": "string", // malicious mining indicator
"mixer": "string", // interaction with mixing services
"fake_token": "string", // fake token creation or usage indicator
"honeypotrelatedaddress": "string" // interaction with honeypot-related addresses
},
"checked_times": 0, // integer — number of times this wallet has been analyzed
"createdAt": "ISO-8601 timestamp", // record creation timestamp
"updatedAt": "ISO-8601 timestamp", // record last update timestamp
"sanctionData": [ { "category": "string | null", // sanction category (may be null) "name": "string | null", // sanction list name "description": "string | null", // sanction description "url": "string | null", // source URL for sanction information "isSanctioned": false, // boolean — whether the wallet is officially sanctioned "createdAt": "ISO-8601 timestamp", // sanction record creation timestamp "updatedAt": "ISO-8601 timestamp" // sanction record last update timestamp } ] }
Error cases:
• 402 Payment Required → x402 payment required — compatible clients settle automatically • 400 Bad Request → malformed network or walletAddress • 500 Internal Server Error → temporary downstream failure
2. Batch Predictive Fraud Detection Tool
ID: predictivefraudbatch
Description: This AI‑powered algorithm forecasts the likelihood of fraudulent activity on a given wallet address before it happens (≈98% accuracy), and performs AML/Anti‑Money‑Laundering checks in batch. Schedule a batch fraud calculation job for a list of wallet addresses. Use this when the user provides a CSV or list of addresses to analyse. Returns a jobid and signature immediately — report the jobid to the user and store both job_id and signature in context, they are required for all follow-up calls. Do NOT poll or wait for results after scheduling.
➡️ Example Use Cases:
• Run fraud batch for this list of addresses on ETH network ? • What is the fraudulent status of this addresses on BNB ?
Inputs:
| Name | Type | Required | Description | | --------------- | ----------------- | -------- | ------------------------------------------------------------------------- | | apiKey | string | ✅* | ChainAware API key — or omit when using x402 payments | | network | string | ✅ | Blockchain network (ETH, BNB,POLYGON,TON,BASE, TRON, HAQQ) | | addresses | array[objects] | ✅ | The list ofwallet address to evaluate |
Outputs (JSON):
{
"message": "Job scheduled successfully.",
"job_id": "0fc5897a-ad64-4f21-88b5-1274d1cfec46",
"signature": "260866090d88bf61bdfb54f0533fe876bfd8ded7339691c50ada9de59a48124a",
"total_items": 5,
"chunks_enqueued": 1,
"status": "pending"
}Error cases:
• 402 Payment Required → x402 payment required — compatible clients settle automatically • 400 Bad Request → malformed network or walletAddress • 500 Internal Server Error → temporary downstream failure
3. Predictive Behaviour Analysis Tool
ID: predictive_behaviour
Description: This AI‑driven engine projects what a wallet address intentions or what address is likely to do next, profiles its past on‑chain history, and recommends personalized actions.
Use this when you need:
• Next‑best‑action predictions and intentions(“Will this address deposit, trade, or stake?”) • A risk‑tolerance and experience profile • Category segmentation (e.g. NFT, DeFi, Bridge usage) • Custom recommendations based on historical patterns
➡️ Example Use Cases:
• “What will this address do next?” • “Is the user high‑risk or experienced?” • “Recommend the best DeFi strategies for 0x1234... on ETH network.”
Inputs:
| Name | Type | Required | Description | | --------------- | ------ | ------------------ | ------------------------------------------------------------------------- | | apiKey | string | ✅* | ChainAware API key — or omit when using x402 payments | | network | string | ✅ | Blockchain network (ETH, BNB,BASE,HAQQ,SOLANA) | | walletAddress | string | ✅ | The wallet address to evaluate |
Outputs (JSON):
{
"message": "string", // e.g. “Success” or error description
"walletAddress": "string", // blockchain wallet address analyzed
"status": "string", // fraud classification result (e.g. “Fraud” | “Not Fraud” | “New Address”)
"probabilityFraud": "0.00–1.00", // decimal probability score indicating fraud risk "token": "string | null", // optional token context for the analysis "chain": "string", // blockchain network identifier (e.g. ETH, BNB,BASE,HAQQ,SOLANA)
"lastChecked": "ISO-8601 timestamp", // last time the wallet was analyzed
"forensic_details": { "cybercrime": "string", // indicator of cybercrime association "money_laundering": "string", // money laundering activity indicator "numberofmaliciouscontractscreated": "string", // malicious contracts deployed by wallet "gas_abuse": "string", // abnormal gas usage indicator "financial_crime": "string", // financial crime activity indicator "darkweb_transactions": "string", // interaction with darkweb-linked wallets "reinit": "string", // contract reinitialization exploit indicator "phishing_activities": "string", // phishing activity indicator "fake_kyc": "string", // fake KYC interaction indicator "blacklist_doubt": "string", // suspected blacklist association "fakestandardinterface": "string", // fake token interface indicator "data_source": "string", // source of forensic intelligence "stealing_attack": "string", // stealing attack indicator "blackmail_activities": "string", // blackmail activity indicator "sanctioned": "string", // sanction exposure indicator "maliciousminingactivities": "string", // malicious mining activity indicator "mixer": "string", // interaction with mixing services "fake_token": "string", // fake token creation/use indicator "honeypotrelatedaddress": "string" // honeypot contract interaction indicator },
"categories": [ { "Category": "string", // wallet interaction category (e.g. DeFi, NFT, Bridge) "Count": 0 // number of transactions/interactions in this category } ],
"riskProfile": [ { "Category": "Risk_Profile", // willingnes to take risk object "Balance_age": 0.0 // 1-10 willingnes to take risk value } ],
"segmentInfo": "string (JSON encoded)", // serialized JSON containing protocol engagement flags (e.g "{\"Maker\":0,\"Aaveborrow\":0,\"Aavelend\":1,\"Lido\":0,\"Uniswap\":1,\"Compoundlend\":0,\"Compoundborrow\":0}")
"experience": { "Type": "string", // descriptor label (e.g. “Experience”) "Value": 0 // numeric experience score level },
"intention": { "Type": "string", // descriptor label (e.g. “Intentions”) "Value": { "Prob_Lend": "Low | Medium | High", "Prob_Trade": "Low | Medium | High", "Prob_Game": "Low | Medium | High", "Prob_NFT": "Low | Medium | High", "ProbStakeETH": "Low | Medium | High", "Prob_Borrow": "Low | Medium | High", "Prob_Gamble": "Low | Medium | High", "Prob_Stake": "Low | Medium | High", "ProbYieldFarm": "Low | Medium | High", "ProbLeveragedStake": "Low | Medium | High", "ProbLeveragedStake_ETH": "Low | Medium | High", "ProbLeveragedLend": "Low | Medium | High", "ProbLeverageLong_ETH": "Low | Medium | High", "ProbLeverageLong": "Low | Medium | High" } },
"protocols": [ { "Protocol": "string", // protocol name (e.g. Uniswap, Curve, MakerDAO) "Count": 0 // number of interactions with this protocol } ],
"userDetails": { "walletagedays": 0, // age of wallet in days "totalbalanceusd": 0.0, // current wallet balance in USD "transaction_count": 0, // total number of transactions executed "wallet_rank": 0 // ranking of wallet in the scoring system },
"riskCapability": 0, // numeric risk capability score
"recommendation": { "Type": "string", // descriptor label (e.g. “Recommendation”) "Value": [ "string" // recommended strategies or actions ] },
"checked_times": 0, // number of times the wallet analysis was executed "createdAt": "ISO-8601 timestamp", // record creation timestamp "updatedAt": "ISO-8601 timestamp", // record last update timestamp
"sanctionData": [ { "category": "string | null", // sanction category "name": "string | null", // sanction list name "description": "string | null", // sanction description "url": "string | null", // reference source URL "isSanctioned": false, // whether the wallet is officially sanctioned "createdAt": "ISO-8601 timestamp", "updatedAt": "ISO-8601 timestamp" } ] }
Error cases:
• 402 Payment Required → x402 payment required — compatible clients settle automatically • 400 Bad Request → malformed network or walletAddress • 500 Internal Server Error → temporary downstream failure
4. Batch Predictive Behaviour Analysis Tool
ID: predictivebehaviourbatch
Description: This AI‑driven engine projects what a wallet address intentions or what address is likely to do next, profiles its past on‑chain history, and recommends personalized actions. Schedule a batch audit (behavioral prediction batch) calculation job for a list of wallet addresses. Use this when the user provides a CSV or list of addresses to analyse. Returns a jobid and signature immediately — report the jobid to the user and store both job_id and signature in context, they are required for all follow-up calls. Do NOT poll or wait for results after scheduling.
Use this when you need:
• Next‑best‑action predictions and intentions(“Will this addresses deposit, trade, or stake?”) • A risk‑tolerance and experience profile for given list of addresses • Category segmentation (e.g. NFT, DeFi, Bridge usage) • Custom recommendations based on historical patterns
➡️ Example Use Cases:
• “What will this addresses do next?” • “Are these users high‑risk or experienced?” • “Recommend the best DeFi strategies for [{ox1..,0x2,0x3}] on ETH network.”
Inputs:
| Name | Type | Required | Description | | --------------- | -------------- | ------------------ | ------------------------------------------------------------------------- | | apiKey | string | ✅* | ChainAware API key — or omit when using x402 payments | | network | string | ✅ | Blockchain network (ETH, BNB,BASE,HAQQ,SOLANA) | | addresses | array[objects] | ✅ | The wallet address to evaluate |
Outputs (JSON):
{
"message": "Job scheduled successfully.",
"job_id": "0fc5897a-ad64-4f21-88b5-1274d1cfec46",
"signature": "260866090d88bf61bdfb54f0533fe876bfd8ded7339691c50ada9de59a48124a",
"total_items": 5,
"chunks_enqueued": 1,
"status": "pending"
}Error cases:
• 402 Payment Required → x402 payment required — compatible clients settle automatically • 400 Bad Request → malformed network or walletAddress • 500 Internal Server Error → temporary downstream failure
5. Predictive Rug‑Pull Detection Tool
ID: predictiverugpull
Description: This AI‑powered engine forecasts which liquidity pools or contracts are likely to perform a “rug pull” in the future (90.1% backtesting accuracy). Use this when you need to warn users before they deposit into risky pools or to monitor smart‑contract security on-chain.
➡️ Example Use Cases:
• “Will this new DeFi pool rug‑pull if I stake my assets?” • “Monitor my LP position for potential future exploits.”
Inputs:
| Name | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------- | | apiKey | string | ✅* | ChainAware API key — or omit when using x402 payments | | network | string | ✅ | Blockchain network (ETH, BNB, BASE, HAQQ) | | walletAddress | string | ✅ | Smart contract or liquidity pool address |
Outputs (JSON):
{
"message": "string", // e.g. “Success” or error description
"contractAddress": "string", // smart contract address analyzed "pairAddress": "string", // liquidity pair address on DEX "contractCreatorAddress": "string | null", // creator address of the contract if known
"risk_score": 0, // numeric internal risk score "risk_status": "string", // qualitative risk level (e.g. “Low Risk”, “Medium Risk”, “High Risk”)
"risk_indicators": { "is_honeypot": 0, // honeypot detection flag "honeypotwithsame_creator": 0, // creator deployed previous honeypots "cantakeback_ownership": 0, // contract allows reclaiming ownership "is_mintable": 0, // token supply can be minted "hidden_owner": 0, // hidden ownership mechanism detected
"buy_tax": 0, // buy transaction tax percentage "sell_tax": 0, // sell transaction tax percentage
"cannot_buy": 0, // trading restriction preventing buys "cannotsellall": 0, // restriction preventing full sell
"is_blacklisted": 0, // blacklist functionality detected "is_whitelisted": 0, // whitelist-only functionality detected
"creator_percent": 0, // percentage of supply owned by creator "lpholderslocked": false, // liquidity lock status
"liquidity": 0.0, // liquidity amount in base token "market_cap": 0, // estimated market capitalization
"isindex": 0, // token listed on DEX
"slippage_modifiable": 0, // contract can modify slippage parameters "transfer_pausable": 0, // transfers can be paused "isantiwhale": 0, // anti-whale protection mechanism "antiwhalemodifiable": 0, // anti-whale parameters modifiable
"trading_cooldown": 0, // cooldown period between trades "personalslippagemodifiable": 0, // per-wallet slippage modification
"isopensource": 0, // contract source verified "is_proxy": 0, // proxy contract indicator
"owner_address": "string", // owner address of contract "ownerchangebalance": 0, // owner ability to modify balances
"selfdestruct": 0, // self-destruct capability "external_call": 0, // external calls present "gas_abuse": 0 // abnormal gas manipulation behavior },
"liquidityEvent": [ { "eventType": "string", // liquidity event type (e.g. add/remove) "amount": 0.0, // liquidity amount affected "token": "string", // token symbol involved in liquidity
"tx_hash": "string", // transaction hash
"from_address": "string", // address initiating liquidity action "fromfraudprobability": "0.00–1.00", // fraud probability score for sender "fromfraudstatus": "string", // fraud classification of sender
"createdAt": "ISO-8601 timestamp" // timestamp of liquidity event } ],
"status": "string", // overall fraud classification of contract "probabilityFraud": "0.00–1.00", // probability of contract being fraudulent
"chain": "string", // blockchain network identifier (e.g. BNB, ETH, BASE, HAQQ) "lastChecked": "ISO-8601 timestamp", // last time contract analysis was performed
"contractCreationTime": "ISO-8601 timestamp | null", // contract deployment timestamp
"forensic_details": { "owner": "object", // owner metadata "privilege_withdraw": 0, // privileged withdraw capability "withdraw_missing": 0, // missing withdraw function "isopensource": 0, // contract source verification status "blacklist": 0, // blacklist functionality "contract_name": "string", // contract/token name "selfdestruct": 0, // self-destruct capability "is_proxy": 0, // proxy contract indicator "approval_abuse": 0 // abnormal token approval behavior },
"checked_times": 0, // number of times contract has been analyzed
"createdAt": "ISO-8601 timestamp", // record creation time "updatedAt": "ISO-8601 timestamp" // last update time }
Error cases:
• 402 Payment Required → x402 payment required — compatible clients settle automatically • 400 Bad Request → malformed network or walletAddress • 500 Internal Server Error → temporary downstream failure
6. Credit Score Tool
ID: credit_score
Description: AI-driven crypto credit/trust scoring for blockchain wallets. Combines fraud probability, on-chain inflow/outflow analytics, and social graph analysis to produce a riskRating from 1 (highest risk) to 9 (highest trust). Designed for DeFi lending protocols that need a fast, single-number creditworthiness signal per wallet.
➡️ Example Use Cases:
• "What is the credit score for this wallet?" • "What's the calculated trust score for this borrower?" • "Calculate credit score before approving this loan."
Inputs:
| Name | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------------- | | apiKey | string | ✅* | ChainAware API key — or omit when using x402 payments | | network | string | ✅ | Blockchain network (ETH) | | walletAddress | string | ✅ | The wallet address to score |
Outputs (JSON):
{
"message": "Success",
"creditData": {
"riskRating": 7,
"walletAddress": "0x..."
}
}| riskRating | Risk Level | Lending Interpretation | |-----------|------------|------------------------| | 9 | Very Low Risk | Prime borrower | | 7–8 | Low Risk | Reliable borrower | | 5–6 | Moderate Risk | Elevated caution | | 3–4 | High Risk | Restricted terms | | 1–2 | Very High Risk | Decline |
Error cases:
• 401 Unauthorized → invalid apiKey (not applicable when using x402 payments) • 400 Bad Request → malformed network or walletAddress • 500 Internal Server Error → temporary downstream failure
7. Token Rank List Tool
ID: tokenranklist
Description: TokenRank analyzes the community of token holders and ranks every token by the strength of its holders. The stronger the token holders, the stronger the token! Use this when you need to know token rank of a token or tokens or compare between different categories and chains. You can use search,filter and sort and pagination which returns a list of tokens.
➡️ Example Use Cases: – “Which is the best token on AI Token category?” – “Compare x token in ETH chain and BNB chain?”
Inputs:
| Name | Type | Required | Description | | --------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------- | | limit | string | ✅ | Number of items ot fetch during pagination | | offset | string | ✅ | Page number(offset) during pagination | | network | string | | Blockchain network to filter (ETH, BNB, BASE, SOLANA) | | sort_by | string | | Sort the returnet tokens based on (e.g.: 'communityRank') | | sortorder | string | | 'ASC' or 'DESC' sorting the value of sortby | | category | string | | Filter based on category of the token (e.g. 'AI Token','RWA Token','DeFi Token','DeFAI Token','DePIN Token') | | contract_name | string | | Search based on contract name |
Outputs (JSON):
{
"message": "string", // e.g. “Successfully fetched records” or error description
"data": {
"total": 0, // integer — total number of matching contracts
"contracts": [
{
"contractAddress": "string", // unique contract or mint address (chain-specific format)
"contractName": "string", // human-readable token name
"ticker": "string", // token symbol (usually uppercase, but not guaranteed)
"chain": "string", // blockchain network (e.g. SOLANA | ETH | BNB | BASE)
"category": "string", // primary category label (e.g. 'AI Token','RWA Token','DeFi Token','DeFAI Token','DePIN Token')
"type": "string", // asset classification (e.g. “token” | “nft”)
"communityRank": 0, // integer — raw ranking based on community metrics
"normalizedRank": 0, // integer — normalized or scaled ranking score
"totalHolders": 0, // integer — total unique wallet holders
"lastProcessedAt": "ISO-8601", // timestamp when analytics were last computed
"createdAt": "ISO-8601", // record creation timestamp
"updatedAt": "ISO-8601" // record last update timestamp
}
]
}
}Error cases:
• 400 Bad Request → malformed network or walletAddress • 500 Internal Server Error → temporary downstream failure
8. Token Rank Single Tool
ID: tokenranksingle
Description: Similar to TokenRank List,Token Rank analyzes the community of token holders and ranks every token by the strength of its holders. Except the token rank and token details the token rank single tool fetches the best holders their details and its globalRank alongside others in same network. Use this when you need to know token rank of a single token based on contract address and exeact chain or network or when you need best holders of specific token in specifc network or chain
➡️ Example Use Cases: – “What is the token rank for token in ETH network?” – "Which are the best holders of this contract token address?” – “What is the token rank and its best holders?”
Inputs:
| Name | Type | Required | Description | | ------------------| ------ | --------- | ------------------------------------------------------------- | | contract_address| string | ✅ | The contract address of the token to evaluate | | network | string | ✅ | Blockchain network to filter (ETH, BNB, BASE, SOLANA) |
Outputs (JSON):
{
"message": "string", // e.g. “Successfully fetched records” or error description
"data": {
"contract": {
"contractAddress": "string", // unique contract or mint address (chain-specific format)
"contractName": "string", // human-readable token name
"ticker": "string", // token symbol (usually uppercase, but not guaranteed)
"chain": "string", // blockchain network (e.g. SOLANA | ETH | BNB | BASE)
"category": "string", // primary category label (e.g. 'AI Token','RWA Token','DeFi Token','DeFAI Token','DePIN Token')
"type": "string", // asset classification (e.g. “token” | “nft”)
"communityRank": 0, // integer — raw ranking based on community metrics
"normalizedRank": 0, // integer — normalized or scaled ranking score
"totalHolders": 0, // integer — total unique wallet holders
"lastProcessedAt": "ISO-8601", // timestamp when analytics were last computed
"createdAt": "ISO-8601", // record creation timestamp
"updatedAt": "ISO-8601" // record last update timestamp
},
"topHolders": [
{
"contractAddress": "string", // associated contract address
"Holder": {
"walletAddress": "string", // holder wallet address
"chain": "string", // blockchain network of the wallet
"balance": "string", // token balance (string to preserve precision)
"walletAgeInDays": 0, // integer — age of wallet in days
"transactionsNumber": 0, // integer — total transaction count
"totalPoints": 0.0, // float — computed wallet scoring metric
"globalRank": 0 // integer — wallet rank across entire system
}
}
]
}
}Error cases:
• 400 Bad Request → malformed network or walletAddress • 500 Internal Server Error → temporary downstream failure
9. Run Token Audit Tool
ID: runtokenaudit
Description: Requests a Token Audit for a given token contract or returns already calculated audit data for requested token. This tool is "get-or-create": it first checks if a completed audit already exists for this contract, and if so returns the FULL risk report immediately. If no audit exists yet, it queues a new one and returns a job_id + "queued" status instead.
Use this tool whenever a user asks to audit, scan, check, or evaluate a token/contract for risk, scam signals, honeypot behavior, ownership risk, or liquidity risk. This should be the FIRST and ONLY tool called for a new request — do not call gettokenaudit_result first "just to check."
➡️ Example Use Cases: – "Audit this token contract for me: 0x..." – "Is this BSC token safe? 0x..." – "Run a risk scan on this contract before I buy" – "Check if this address is a honeypot"
Inputs:
| Name | Type | Required | Description | | ------------------| ------ | --------- | ---------------------------------------------------------------------------------------------------------------- | | contract_address| string | ✅ | The contract address of the token to evaluate | | network | string | ✅ | The network/chain the token lives on (e.g. 'arbitrum', 'avalanche', 'base', 'bsc', 'eth', 'optimism', 'polygon') |
Outputs (JSON):
📤 Response — TWO possible shapes, check which one you got: 1.Cached / already audited → audit_status = "complete" Full risk report is returned immediately (same schema as gettokenaudit_result). Answer the user's question directly from this data. No further tool calls needed.
2.Not yet audited → no honeypot_analysis field, instead:
{
"contract_address": "string",
"chain": "string",
"job_id": "string",
"status": "queued",
"message": "string"
}⚠️ Notes: • Do not re-trigger a new audit for a contract that returns a "queued"/"running" job already in progress. • Always first check if token was earlier audited based on response so you get directly the audited token result instead of scheduling new calculation.
Error cases:
• 400 Bad Request → malformed network or walletAddress • 500 Internal Server Error → temporary downstream failure
10. Get Token Audit Result Tool
ID: gettokenaudit_result
Description: Fetches the current status or final results of a previously triggered Token Audit job for a given contract address and chain. This is the SECOND step of the audit workflow, used to poll for and retrieve the full risk report after "Run Token Audit" has been called. Call this tool immediately after "Run Token Audit" to check progress, and repeatedly (poll) until the response's audit_status field equals "complete". While audit_status is anything else (e.g. "queued", "running", "pending"), treat the result as not-yet-ready: do not summarize partial/empty module data to the user, just report that the audit is still in progress (optionally showing elapsed time if available) and poll again shortly. Once audit_status = "complete", this tool returns a full multi-module risk report — covering ownership control, liquidity health, supply/mint risk, transfer integrity, approve/permit safety, reentrancy, honeypot behavior, and an aggregated 0-100 risk score with verdict. Use this data to directly answer the user's question about token safety, risk factors, or red flags — do not fetch or re-trigger a new audit if a completed result already exists for this contract.
➡️ Example Use Cases: – "Is my audit for this token ready yet?" – "What's the risk score and verdict for this contract?" – "Who owns this token, can they mint or blacklist?" – "Is this a honeypot? What are the flags?" – "Give me the full breakdown of this contract's liquidity and ownership risk
Inputs:
| Name | Type | Required | Description | | ------------------| ------ | --------- | ---------------------------------------------------------------------------------------------------------------- | | contract_address| string | ✅ | The contract address of the token to evaluate | | network | string | ✅ | The network/chain the token lives on (e.g. 'arbitrum', 'avalanche', 'base', 'bsc', 'eth', 'optimism', 'polygon') |
Outputs (JSON):
{
"contract_address": "string",
"chain": "string",
"audit_status": "string",
"token_name": "string",
"token_symbol": "string",
"token_decimals": "integer",
"token_creator": "string",
"token_feeder": "string",
"source_verified": "boolean",
"is_proxy": "boolean",
"behavioralishoneypot": "boolean",
"honeypot_analysis": {
"verdict": "string",
"score": "integer",
"findings": [
{
"rule": "string",
"severity": "string",
"function": "string or null" ,
"detail": "string"
}
],
"flags": [
"string"
]
},
"aggregate": {
"verdict": "string",
"risk_score": "integer",
"primary_signal": "string",
"simulate": "boolean",
"version": "string",
"duration_ms": "integer",
"last_run": "ISO-8601"
},
"quick_stats": [
{
"label": "string",
"value": "string",
"tone": "string"
},
{
"label": "string",
"value": "string",
"tone": "string"
},
{
"label": "string",
"value": "string",
"tone": "string"
}
],
"modules": {
"ownership": {
"status": "string",
"risk_score": "integer",
"owner_address": "string",
"owneriseoa": "boolean",
"ownerisrenounced": "boolean",
"blast_radius": "critical",
"can_mint": "boolean",
"can_pause": "boolean",
"can_blacklist": "boolean",
"can_upgrade": "boolean",
"can_drain": "boolean",
"has_timelock": "boolean",
"has_shadow": "boolean"
},
"liquidity": {
"status": "string",
"summary": "string",
"risk_score": "integer",
"pool_count": "integer",
"unknown_pool": "boolean",
"invariants": [
{
"code": "string",
"label": "string",
"status": "string",
"severity": "string",
"detail": "string"
}
]
},
"supply": {
"status": "pass",
"risk_score": "integer",
"has_mint": "boolean",
"deployer_pct": "decimal",
"hidden_mint": "boolean"
},
"transfer": {
"status": "pass",
"risk_score": "integer",
"method": "string",
"monitoring": "boolean",
"invt1pass": "boolean",
"invt2pass": "boolean",
"invt3pass": "boolean",
"invt4pass": "boolean",
"invt5pass": "boolean",
"invt6pass": "boolean",
"invt7pass": "boolean"
},
"pausability": {
"status": "string",
"applicable": "boolean"
},
"approve": {
"status": "string",
"risk_score": "integer",
"method": "string",
"coverage": "string",
"inv1_pass": "boolean",
"inv2_pass": "boolean",
"inv3_pass": "boolean",
"inv5_pass": "boolean",
"inv6_pass": "boolean"
},
"permit": {
"status": "string",
"applicable": "boolean"
},
"reentrancy": {
"status": "string",
"risk_score": "integer"
}
}
}⚠️ Notes: • If audit_status is not "complete", most module/aggregate fields may be null, empty, or stale — do not present them as final results. • A high risk_score or "high"/"critical" tone/severity fields indicate elevated danger; surface these prominently rather than burying them under passing modules.
Error cases:
• 400 Bad Request → malformed network or walletAddress • 500 Internal Server Error → temporary downstream failure
11. Agents Trust Score List Tool
ID: agentstrustscore_list
Description: The ChainAware Agent Trust Score is a 0-1000 score that measures how safe it is to interact with any ERC-8004 registered AI agent. Unlike voting-based reputation systems - where agents can upvote each other to manufacture trust - the Agent Trust Score is derived entirely from on-chain behavioral history. It cannot be earned in hours. It cannot be faked with a cluster of fresh wallets. It reflects the real-world track record of the human or entity controlling the agent. As agentic commerce scales - with AI agents autonomously completing purchases on behalf of consumers across ChatGPT, Google Gemini, and Shopify - the question of which agents can be trusted to transact is no longer theoretical. ChainAware answers it with on-chain evidence, not peer endorsements. It returns a list of Agents and their result.
➡️ Example Use Cases: – Give me a list of Agents and their trust score?” – “Which is the best Agent registered after 2025-01-01?”
Inputs:
| Name | Type | Required | Description | | ------------------| ------ | --------- | ---------------------------------------------------------------------------------------------------------------- | | page | string | ✅ | Page number(page) during pagination | | limit | string | ✅ | Number of items ot fetch during pagination | | sortby | string | X | Sort the returned agents based on e.g.: 'registeredat' | | sortorder | string | X | but required if sortby 'asc' or 'desc' sorting the value of sort_by (default desc) | | registered_after| string | X | Filter based on datetime when the Agent was registered |
Outputs (JSON):
{
"total": "integer",
"page": 1,
"limit": 2,
"results": [
{
"chain_id": "integer",
"agent_id": "integer",
"owner_address": "string",
"agent_wallet": "string",
"agent_uri": "string",
"meta_name": "string",
"registered_at": "ISO-8601",
"reputation_score": "integer",
"trust_score": "integer",
"trust_tier": "string"
},
{
"chain_id": "integer",
"agent_id": "integer",
"owner_address": "string",
"agent_wallet": "string",
"agent_uri": "string",
"meta_name": "string",
"registered_at": "ISO-8601",
"reputation_score": "integer",
"trust_score": "integer",
"trust_tier": "string"
}
]
}Error cases:
• 400 Bad Request → malformed network or walletAddress • 500 Internal Server Error → temporary downstream failure
12. Agents Trust Score Single Tool
ID: agentstrustscore_single
Description: Similar to Agent Trust List, Agent Trust Score Single is a 0-1000 score that measures how safe it is to interact with any ERC-8004 registered AI agent. Unlike voting-based reputation systems - where agents can upvote each other to manufacture trust - the Agent Trust Score is derived entirely from on-chain behavioral history. It cannot be earned in hours. It cannot be faked with a cluster of fresh wallets. It reflects the real-world track record of the human or entity controlling the agent. As agentic commerce scales - with AI agents autonomously completing purchases on behalf of consumers across ChatGPT, Google Gemini, and Shopify - the question of which agents can be trusted to transact is no longer theoretical. ChainAware answers it with on-chain evidence, not peer endorsements. It returns the single details in depth for a requested Agent.
➡️ Example Use Cases: – "What is the trust score for this agent id 12314 on chain_id 56?”
Inputs:
| Name | Type | Required | Description | | ------------------| ------ | --------- | ---------------------------------------------------------------------------------------------------------------- | | agentid | integer | ✅ | Agent id returned from agentstrustscorelist Tool | | chainid | integer | ✅ | Chain id where Agent is deployed/registred previously fetched from agentstrustscorelist Tool |
Outputs (JSON):
{
"agent_id": "integer",
"chain": "string",
"chain_id": "integer",
"owner_address": "string",
"agent_wallet": "string",
"wallet_verified": "boolean",
"agent_uri": "string",
"registered_at": "ISO-8601",
"fetched_at": "ISO-8601",
"error": "string",
"meta_name": "string",
"meta_description": "string",
"meta_image": "string",
"metadata_json": {
"type": "string",
"name": "string",
"description": "string",
"image": "string",
"active": "boolean",
"supportedTrust": "array[string]"
},
"registration": {
"agent_name": "string",
"agent_desc": "string",
"fetch_status": "string",
"fetched_at": "ISO-8601",
"raw_json": {
"type": "string",
"name": "string",
"description": "string",
"image": "string",
"active": "boolean",
"supportedTrust": "array[string]"
}
},
"wallets": [
{
"walletchainid": "integer",
"wallet_address": "string",
"source": "registry",
"fetched_at": "ISO-8601"
}
],
"reputation_score": "string",
"trust_score": "integer",
"trust_tier": "string",
"trust_flags": "array[string]"
}Error cases:
• 400 Bad Request → malformed network or walletAddress • 500 Internal Server Error → temporary downstream failure
13. Check Batch Job Status
ID: checkjobstatus
Description: Check the progress of a scheduled batch calculation job. Returns counts only (completed, failed, pending) — no wallet data. Call this when the user asks whether a job is done or how it is progressing. If status is 'processing' or 'pending', inform the user and do not call getjobresults. Only suggest fetching results when status is 'completed' or 'partial'. Both jobid and signature from schedulecalculation are required to call this tool. Never call this without both values present in context.
➡️ Example Use Cases:
• What is the status of the job id 0fc5897a-ad64-4f21-88b5-1274d1cfec46 using this signature 260866090d88bf61bdfb54f0533fe876bfd8ded7339691c50ada9de59a48124a ?
Inputs:
| Name | Type | Required | Description | | --------------- | ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------- | | jobid | string | ✅ | The job ID returned by scheduled calculation (predictivefraudbatch or predictivebehaviour_batch) | | signature | string | ✅ | The signature returned by scheduled calculation (predictivefraudbatch or predictivebehaviourbatch). Required for access |
Outputs (JSON):
{
"job_id": "0fc5897a-ad64-4f21-88b5-1274d1cfec46",
"status": "partial",
"chain": "ETH",
"total_items": 5,
"completed_items": 1,
"failed_items": 4,
"pending_items": 0,
"expires_at": "2026-07-01T13:51:20.000Z"
}Error cases:
• 403 Unauthorized → invalid apiKey (not applicable when using x402 payments) • 403 Unauthorized → invalid signature • 400 Bad Request → malformed network or walletAddress • 500 Internal Server Error → temporary downstream failure
14. Get Batch Job Results
ID: getjobresults
Description: Retrieve the results of a completed or partially completed batch job. Only call this when checkjobstatus shows status is 'completed' or 'partial'. Returns a list of completed wallet addresses and the shared chain/network — use these to query the main backend for actual wallet analysis data. This does NOT return wallet data directly, only the address list needed to fetch it. Both jobid and signature from schedulecalculation are required to call this tool. Never call this without both values present in context.
➡️ Example Use Cases:
• What is the result of the job id 0fc5897a-ad64-4f21-88b5-1274d1cfec46 using this signature 260866090d88bf61bdfb54f0533fe876bfd8ded7339691c50ada9de59a48124a ?
Inputs:
| Name | Type | Required | Description | | --------------- | ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------- | | jobid | string | ✅ | The job ID returned by scheduled calculation (predictivefraudbatch or predictivebehaviour_batch) | | signature | string | ✅ | The signature returned by scheduled calculation (predictivefraudbatch or predictivebehaviourbatch). Required for access |
Outputs (JSON):
```json { "message": "string", // e.g. “Success” or error description "data":[{ "walletAddress": "string", // blockchain wallet address analyzed "status": "string", // fraud classification result (e.g. “Fraud” | “Not Fraud” | “New Address”)
"probabilityFraud": "0.00–1.00", // decimal probability score indicating fraud risk "token": "string | null", // optional token context for the analysis "chain": "string", // blockchain network identifier (e.g. ETH, BNB,BASE,HAQQ,SOLANA)
"lastChecked": "ISO-8601 timestamp", // last time the wallet was analyzed
"forensic_details": { "cybercrime": "string", // indicator of cybercrime association "money_laundering": "string", // money laundering activity indicator "numberofmaliciouscontractscreated": "string", // malicious contracts deployed by wallet "gas_abuse": "string", // abnormal gas usage indicator "financial_crime": "string", // financial crime activity indicator "darkweb_transactions": "string", // interaction with darkweb-linked wallets "reinit": "string", // contract reinitialization exploit indicator "phishing_activities": "string", // phishing activity indicator "fake_kyc": "string", // fake KYC interaction indicator "blacklist_doubt": "string", // suspected blacklist association "fakestandardinterface": "string", // fake token interface indicator "data_source": "string", // source of forensic intelligence "stealing_attack": "string", // stealing attack indicator "blackmail_activities": "string", // blackmail activity indicator "sanctioned": "string", // sanction exposure indicator "maliciousminingactivities": "string", // malicious mining activity indicator "mixer": "string", // interaction with mixing services "fake_token": "string", // fake token creation/use indicator "honeypotrelatedaddress": "string" // honeypot contract interaction indicator },
"categories": [ { "Category": "string", // wallet interaction category (e.g. DeFi, NFT, Bridge) "Count": 0 // number of transactions/interactions in this category } ],
"riskProfile": [ { "Category": "Risk_Profile", // willingnes to take risk object "Balance_age": 0.0 // 1-10 willingnes to take risk value } ],
"segmentInfo": "string (JSON encoded)", // serialized JSON containing protocol engagement flags (e.g "{\"Maker\":0,\"Aaveborrow\":0,\"Aavelend\":1,\"Lido\":0,\"Uniswap\":1,\"Compoundlend\":0,\"Compoundborrow\":0}")
"experience": { "Type": "string", // descriptor label (e.g. “Experience”) "Value": 0 // numeric experience score level },
"intention": { "Type": "string", // descriptor label (e.g. “Intentions”) "Value": { "Prob_Lend": "Low | Medium | High", "Prob_Trade": "Low | Medium | High", "Prob_Game": "Low | Medium | High", "Prob_NFT": "Low | Medium | High", "ProbStakeETH": "Low | Medium | High", "Prob_Borrow": "Low | Medium | High", "Prob_Gamble": "Low | Medium | High", "Prob_Stake": "Low | Medium | High", "ProbYieldFarm"
README truncated. View on GitHub
