DJD Agent Score API is a wallet screening API for paid agent workflows on Base. Start with one decision before payout or route execution. Add history, forensics, monitoring, and alerts later when the workflow needs more depth.
Use the free basic score endpoint first. It gives you score, tier, confidence, and recommendation with no account required. That is the fastest way to test the wedge.
Human teams usually use a monthly API key. Autonomous callers can pay per request with x402 using USDC on Base. The billing choice comes after the screening decision.
x402-agent-score, djd-agent-score, djd-agent-score-mcp, and the Python package are already published for teams that want a lighter integration path.
Use this when you want to test the score or add a lightweight screening step before payout. It is the fastest proof the product can give you.
curl "https://djdagentscore.dev/v1/score/basic?wallet=0x3E4Ef1f774857C69E33ddDC471e110C7Ac7bB528"
Pay monthly, send a bearer token, and use the same paid endpoints from your backend or protocol service when screening becomes part of production.
curl \ -H "Authorization: Bearer djd_live_..." \ "https://djdagentscore.dev/v1/score/full?wallet=0x3E4Ef1f774857C69E33ddDC471e110C7Ac7bB528"
Use the published Hono middleware when you want to screen the payer wallet before your paid route does work.
npm i x402-agent-score
import { agentScoreGate } from 'x402-agent-score'
app.use('/premium/*', agentScoreGate({
minScore: 25,
onUnknown: 'allow',
}))
Use the published TypeScript client when you want a small wrapper instead of raw HTTP calls. It defaults to the production API, and you can add apiKey when you move from free lookups to monthly-plan access.
npm install djd-agent-score
import { DJDAgentScore } from 'djd-agent-score'
const client = new DJDAgentScore({
// apiKey: 'djd_live_...', // Optional for paid endpoints on monthly plans
})
const score = await client.getBasicScore(
'0x3E4Ef1f774857C69E33ddDC471e110C7Ac7bB528',
)
console.log(score.score, score.tier, score.confidence)
Use the Python client when you are integrating from backend services, notebooks, or agent frameworks and want the same screening logic in Python.
pip install djd-agent-score
from djd_agent_score import AgentScoreClient
client = AgentScoreClient()
score = client.get_score(
"0x3E4Ef1f774857C69E33ddDC471e110C7Ac7bB528"
)
print(score.score, score.tier, score.confidence)
Many wallets on Base are still new or lightly used. That means plenty of first-time lookups will come back as Unverified or Emerging, especially for wallets with short histories and few counterparties. In practice, that usually means thin data, not proven fraud, so the right default is to screen first and add stricter policy later.
x402 lets software pay software per request with USDC on Base. For AgentScore, that means an autonomous caller can pay for a score lookup or a protected route without opening a monthly account first. The payment rail is separate from the screening decision.
| Mode | Best for | How it works |
|---|---|---|
| GET /v1/score/basic | Testing and lightweight screening | No auth. 10 requests per IP in a rolling 24-hour window. Returns score, tier, confidence, and recommendation. |
| API key | Human developers running production workflows | Use Authorization: Bearer djd_live_... with a monthly plan from pricing. |
| x402 | Autonomous callers paying per request | Paid endpoints also accept x402 on Base. If no valid API key is present, the paid route falls back to x402. |
Insumer is an optional third-party attestation service used inside the Identity dimension. AgentScore asks it for a signed yes/no answer on a handful of multi-chain ownership checks. It does not replace the core score, and it does not get to override the rest of the model. Treat it as supporting evidence after screening.
| Question | Answer | Why it matters |
|---|---|---|
| What signal does it add? | Signed booleans for a small set of multi-chain asset or identity conditions. | Adds optional identity points on top of the screening score when you want extra context. |
| Does it expose balances? | No. The service returns pass/fail attestations, not raw wallet balances. | Keeps the identity signal narrower than “full wallet dossier” style data collection. |
| What if Insumer is down? | The score still works. That wallet just gets no Insumer contribution for that request. | It is a supporting identity input, not a hard dependency for the entire product. |
| Path | Use | Access |
|---|---|---|
| GET /v1/score/basic | Fast wallet screening with score, tier, confidence, and recommendation. | Free |
| GET /v1/score/full | Deeper breakdown, integrity flags, and explainability for a wallet decision. | API key or x402 ($0.10) |
| GET /v1/score/history | Trend and trajectory when you need more than a single snapshot. | API key or x402 ($0.15) |
| GET /v1/forensics/summary | Wallet risk summary, incidents, and penalties for investigation. | API key or x402 |
| POST /v1/monitor | Create monitoring subscriptions once you need workflow ops and alerts. | API key plan |
| POST /v1/webhooks | Create wallet-scoped alert webhooks for watched wallets. | API key plan |
API-key plans no longer need to hard-stop the moment a monthly limit is crossed. Each plan includes a small grace window so a live workflow is less likely to fail because it hit quota mid-month.
{
"wallet": "0x3e4ef1f774857c69e33dddc471e110c7ac7bb528",
"score": 52,
"tier": "Established",
"confidence": 0.74,
"recommendation": "proceed_with_caution",
"modelVersion": "2.0.0",
"lastUpdated": "2026-03-15T08:00:00.000Z",
"scoreFreshness": 0.91
}
Webhook and monitoring deliveries are wallet-scoped and signed with an HMAC secret returned on creation. Keep the secret you receive from POST /v1/webhooks or POST /v1/monitor so your endpoint can verify the payload.
{
"event": "anomaly.score_drop",
"wallet": "0x3e4ef1f774857c69e33dddc471e110c7ac7bb528",
"timestamp": "2026-03-15T08:00:00.000Z",
"data": {
"old_score": 61,
"new_score": 42,
"change": -19,
"recommendation": "flagged_for_review"
}
}
| Package | Use | Link |
|---|---|---|
| x402-agent-score | Hono middleware for screening payer wallets before a paid x402 route runs. | npm |
| djd-agent-score | TypeScript/JavaScript client for the API. | npm |
| djd-agent-score-mcp | MCP server for Claude, GPT, Cursor, or other MCP clients. | npm |
| djd-agent-score (Python) | Python client with repo-based agent framework examples. | PyPI |
The full spec is below. Expand any route to see parameters, request bodies, response schemas, and examples. If the interactive bundle ever fails to load, use the raw spec at https://djdagentscore.dev/openapi.json. Human-readable uptime and job status live on the public status page.