Batch scoring
POST /v1/score/batch
Score up to 25 wallets in one request. Each result matches the /v1/score shape.
POST https://agent-api.fairscale.xyz/v1/score/batch
curl -X POST "https://agent-api.fairscale.xyz/v1/score/batch" \
-H "fairkey: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"wallets": [
"FRGumQszUGLTtfgH3gDwzG256pL4P8Cj3DDGAPCmBFka",
"5G5HDvbib4CyHxVgm4RHiVY5RfbDuFfp6BiH5xgZXczT"
],
"task": "trust_focused"
}'
| Field | Required | Description |
|---|---|---|
wallets | Yes | Array of addresses, max 25 |
task | No | Scoring profile applied to all wallets |
Verified response (Jul 2026):
{
"total": 2,
"scored": 2,
"results": [
{ "wallet": "FRGumQszUGLTtfgH3gDwzG256pL4P8Cj3DDGAPCmBFka", "score": 24, "tier": "bronze" },
{ "wallet": "5G5HDvbib4CyHxVgm4RHiVY5RfbDuFfp6BiH5xgZXczT", "score": 11, "tier": "bronze" }
],
"meta": { "provider": "FairScale", "scored_at": "2026-07-04T15:01:41.249Z" }
}
Errors: too_many_wallets if more than 25. See Error Codes.
const batch = await client.scoreBatch(wallets, { task: "trust_focused" });
const approved = batch.results.filter((r) => !r.error && r.score >= 60);
Directory
GET /v1/directory
Paginated agent index with filters and sorting.
GET https://agent-api.fairscale.xyz/v1/directory
| Parameter | Default | Description |
|---|---|---|
page | 1 | Page number |
limit | 25 | Results per page (max 100) |
sort | agent_fairscore | Sort field (see below) |
source | - | Registry filter: said, erc8004, sati |
min_score | - | Minimum fairscore |
verified_only | - | true for registry-verified only |
recommendation | - | trusted, caution, high_risk, unverified |
search | - | Search name or description |
has_attestations | - | true for agents with on-chain attestations |
Sort values: agent_fairscore, verification, wallet_history, work_history, network_quality, peer_reputation.
curl "https://agent-api.fairscale.xyz/v1/directory?verified_only=true&limit=2" \
-H "fairkey: YOUR_KEY"
Verified response (Jul 2026):
{
"total": 3443,
"page": 1,
"limit": 2,
"total_pages": 1722,
"agents": [
{
"wallet": "EZkoXXZ5HEWdKwfv7wua7k6Dqv8aQxxHWNakq2gG2Qpb",
"name": "Atelier",
"fairscore": 28,
"tier": "bronze",
"recommendation": { "tier": "caution", "label": "Use with Caution" },
"sources": ["said"]
}
],
"meta": { "generated_at": "2026-07-04T15:01:41.742Z" }
}
Cache: 2 min.
Leaderboard
GET /v1/leaderboard
Top agents by metric.
GET https://agent-api.fairscale.xyz/v1/leaderboard?metric=agent_fairscore&limit=5
| Parameter | Default | Description |
|---|---|---|
metric | agent_fairscore | Same sort fields as directory |
limit | 25 | Number of results |
Verified response (Jul 2026):
{
"metric": "agent_fairscore",
"total": 3444,
"showing": 5,
"leaderboard": [
{
"rank": 1,
"wallet": "EZkoXXZ5HEWdKwfv7wua7k6Dqv8aQxxHWNakq2gG2Qpb",
"name": "Atelier",
"value": 28,
"agent_fairscore": 28,
"sources": ["said"]
}
]
}
Cache: 5 min.