Risk Score · API
The same check, one HTTP call
Call it before your agent pays a stranger, or before you let a stranger's agent check out. Keys are free and created in your account.
Request
# deterministic: chain and agent id
GET https://app.merces.ai/api/v1/check/base/1380
Authorization: Bearer mk_live_…
# or search by anything a person would paste
GET /api/v1/check?q=eip155:8453:1380
GET /api/v1/check?q=0x3c0820e2dabd5feae1fd03b78079dee15c7f83d8
GET /api/v1/check?q=capminal.aiSemantics
- /check/{chain}/{agentId} is deterministic: a report or a 404. Use it before money moves.
- /check?q= resolves anything a person pastes. status is report (one match), candidates (several; each carries its check path) or none. A report says how it matched in matchedAs; anything but exact or reference is fuzzy, so confirm the agent.
- Every factor carries evidence, the values its title was written from. Branch on those, not on the prose. Factor ids are stable within schemaVersion.
- id is eip155:<chainId>:<agentId>, the same on every surface. Agent ids are strings. Times are UTC ISO 8601. dataAsOf says how far the indexed data reaches.
- score is always null in this release. Do not treat its absence as safety.
- Errors share one envelope: { error: { code, message }, requestId }. Every response carries X-Request-Id and X-RateLimit-* headers; 60 requests a minute per key.
- Agent records: GET /api/v1/agents/{chain}/{agentId}. Machine-readable contract: openapi.json.
Response
{
"status": "report",
"requestId": "6d3f…",
"report": {
"schemaVersion": "1.0",
"id": "eip155:8453:1380",
"agent": { "chainKey": "base", "agentId": "1380", "name": "Captain Dackie", … },
"query": null,
"matchedAs": "exact",
"checkedAt": "2026-10-20T21:04:11.000Z",
"dataAsOf": { "chainKey": "base", "latestRegistrationAt": "…", "latestReviewAt": "…" },
"listed": true,
"listingFlags": [],
"score": null,
"summary": { "known": 15, "attention": 0, "unknown": 1, "headline": "15 factors known, 0 need attention, 1 unknown." },
"factors": [
{ "id": "registration_age", "group": "identity", "status": "ok",
"title": "Registered 258 days ago", "detail": "…",
"evidence": { "registeredAt": "2026-02-04T10:15:09.000Z", "ageDays": 258 } },
{ "id": "reviews", "group": "reputation", "status": "ok",
"title": "1,536 reviews from 1,514 reviewers", "detail": "…",
"evidence": { "total": 1536, "reviewers": 1514, "last30d": 3, "averageValue": 99.75, … } },
…
],
"note": "merces.ai does not compute a risk score yet. …"
}
}