User Segmentation API¶

The User Segmentation API classifies any wallet address into a quality segment based on its on-chain behaviour history. Use it to distinguish high-value users from low-value or low-intent users at the moment they connect to your protocol — without requiring any off-chain identity data.

Base URL: https://enterprise.api.chainaware.ai

Authentication: x-api-key header required.

Subscription: Enterprise

Supported networks: ethereum, bsc, polygon

The Segmentation Model¶

ChainAware's segmentation is modelled on the ABC classification widely used in traditional finance, adapted for on-chain behaviour:

Segment	Share of users	Behaviour
A	~10%	Highest on-chain activity, transaction volume, and protocol engagement. These wallets generate the majority of revenue for most protocols.
B	~20%	Moderate activity and engagement. Profitable but not consistently high-value.
C	~70%	Low activity, low transaction value, or high churn likelihood. Often generate more costs than revenue in incentivised protocols.

In practice: for every 100 wallets that connect to your protocol, around 10 are likely your most valuable future users — but without segmentation data, they look identical to the other 90 at the point of connection.

The API also returns a walletQuality integer score (0–100) for finer-grained ranking within segments.

POST /segmentation/wallet-segment¶

Request¶

Headers

Header	Type	Required	Description
`x-api-key`	string	Yes	Your ChainAware API key
`Content-Type`	string	Yes	`application/json`

Body

Field	Type	Required	Description
`walletAddress`	string	Yes	The wallet address to classify
`network`	string	Yes	Blockchain network — `ethereum`, `bsc`, or `polygon`

Example request

curl -X POST https://enterprise.api.chainaware.ai/segmentation/wallet-segment \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "network": "ethereum"
  }'

Response¶

Field	Type	Description
`message`	string	Result status message
`data.walletAddress`	string	The queried wallet address
`data.walletQuality`	integer	Quality score from 0 (lowest) to 100 (highest)
`data.segmentInfo`	string	Segment classification — `"A"`, `"B"`, or `"C"`

Example response

{
  "message": "Wallet segment retrieved",
  "data": {
    "walletAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "walletQuality": 87,
    "segmentInfo": "A"
  }
}

Interpreting the Response¶

segmentInfo — use the A/B/C label for straightforward routing decisions:
- Segment A: offer premium conditions, priority support, or advanced product features
- Segment B: standard onboarding; consider targeted engagement to move toward A
- Segment C: default experience; protect incentive spend by capping rewards or requiring additional interaction before unlocking benefits

walletQuality — use the 0–100 score when you need finer ranking within a segment. For example, to rank a waiting list, prioritise liquidity mining allocations, or set dynamic fee tiers.

Common Use Cases¶

Dynamic onboarding — route Segment A wallets directly to advanced features; walk Segment C wallets through guided flows
Incentive allocation — cap airdrop or liquidity mining rewards for Segment C wallets to protect programme ROI
Fee tier personalisation — offer reduced fees or higher limits to high-quality wallets to improve retention
Marketing prioritisation — allocate manual outreach and relationship-building effort toward Segment A wallets
Combined with fraud screening — call /fraud/check and /segmentation/wallet-segment together at wallet-connect to gate risk and personalise simultaneously