predictive_behaviour_batch¶

Schedules a batch behavioural profiling job for a list of wallet addresses. Returns a job_id and signature immediately - do not wait for results after scheduling. Use check_job_status to poll progress and get_job_results to retrieve completed results.

Returns the same rich output as predictive_behaviour - experience score, 14 intent signals, categories, protocol history, recommendations - for each address in the batch.

Use this tool when a user provides a CSV or list of addresses for behavioural profiling, segmentation, or personalisation.

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

Supported Networks¶

Identifier	Network
`ETH`	Ethereum
`BNB`	BNB Smart Chain
`BASE`	Base
`HAQQ`	HAQQ
`SOLANA`	Solana

Input Schema¶

Field	Type	Required	Description
`apiKey`	string	Yes	Your ChainAware API key
`network`	string	Yes	Blockchain network identifier (one of the values above)
`addresses`	array of objects	Yes	List of wallet addresses to profile

Output Schema¶

The tool returns immediately with job metadata - no wallet results yet.

{
  "message": "Job scheduled successfully.",
  "job_id": "0fc5897a-ad64-4f21-88b5-1274d1cfec46",
  "signature": "260866090d88bf61bdfb54f0533fe876bfd8ded7339691c50ada9de59a48124a",
  "total_items": 5,
  "chunks_enqueued": 1,
  "status": "pending"
}

Field	Type	Description
`job_id`	string	Unique identifier for this batch job - store this, required for all follow-up calls
`signature`	string	Security signature - store this alongside `job_id`, required for all follow-up calls
`total_items`	integer	Total number of wallet addresses submitted
`chunks_enqueued`	integer	Number of processing chunks queued
`status`	string	Initial job status - always `"pending"` on creation

Important: Store both job_id and signature immediately. Both are required to check status and retrieve results. Neither can be recovered if lost.

Batch Workflow¶

1. predictive_behaviour_batch  →  schedule job, store job_id + signature
2. check_job_status            →  poll until status is "completed" or "partial"
3. get_job_results             →  retrieve wallet behavioural profiles

Do not poll immediately after scheduling - allow time for the job to process.

Code Examples¶

Node.js¶

const job = await client.callTool({
  name: "predictive_behaviour_batch",
  arguments: {
    apiKey: process.env.CHAINAWARE_API_KEY,
    network: "ETH",
    addresses: [
      { walletAddress: "0xABC..." },
      { walletAddress: "0xDEF..." },
      { walletAddress: "0x123..." }
    ]
  }
});

const { job_id, signature } = job;
// Store both - needed for check_job_status and get_job_results

Python¶

job = await session.call_tool("predictive_behaviour_batch", {
    "apiKey": os.environ["CHAINAWARE_API_KEY"],
    "network": "ETH",
    "addresses": [
        {"walletAddress": "0xABC..."},
        {"walletAddress": "0xDEF..."},
        {"walletAddress": "0x123..."}
    ]
})

job_id = job["job_id"]
signature = job["signature"]

Example Agent Prompts¶

"Profile these ETH wallets for my segmentation campaign: 0xABC..., 0xDEF..., 0x123..."
"What will these addresses do next on BNB? [list]"
"Are these users high-risk or experienced? [list of addresses]"
"Recommend DeFi strategies for this batch of wallets on ETH: [list]"

Use Cases¶

Audience segmentation - profile a full user base and segment by experience, intent, and protocol usage
Campaign targeting - identify Power Traders, Yield Farmers, and Newcomers across thousands of wallets before a campaign launch
Cohort analysis - group wallets into behavioural cohorts for lifecycle messaging
Airdrop strategy - identify and prioritise high-experience wallets in reward distribution

Error Codes¶

Code	Meaning
`403`	Invalid or missing `apiKey`
`400`	Malformed `network` or address list
`500`	Temporary backend failure - retry after a short delay

predictive_behaviour - single-wallet behavioural profiling for real-time use
check_job_status - poll batch job progress
get_job_results - retrieve completed batch results