DJD Agent Score

DJD Agent Score

在资金流转前、过程中和之后，治理 Base 上由 Agent 驱动的商业活动。

DJD Agent Score 是 Base 上 Agent 钱包的信任与治理层。目前最明确的采用路径仍然很简单：在 Agent 发送资金或履行付费 x402 请求之前，筛查交易对手。

在线 API · API 文档 · OpenAPI 规范 · 排行榜

---

从这里开始：为 x402 路由设置准入控制

如果你运行的是付费 Hono 端点，这是最适合作为首次集成的方案。

import { Hono } from 'hono'
import { agentScoreGate } from 'x402-agent-score'

const app = new Hono()

app.use(
  '/premium/*',
  agentScoreGate({
    minScore: 60,
    onUnknown: 'reject',
  }),
)

app.post('/premium/search', async (c) => {
  return c.json({ ok: true })
})

安装：

npm i x402-agent-score

参考示例：examples/x402-hono.ts

---

免费查询

无需注册、API 密钥或付款，即可为任意钱包评分。免费层级每天包含 10 次基础查询。

curl "https://djdagentscore.dev/v1/score/basic?wallet=0x3E4Ef1f774857C69E33ddDC471e110C7Ac7bB528"

返回：

{
  "wallet": "0x3E4Ef1f774857C69E33ddDC471e110C7Ac7bB528",
  "score": 39,
  "tier": "Emerging",
  "confidence": 0.16,
  "recommendation": "insufficient_history",
  "modelVersion": "2.5.0",
  "lastUpdated": "2026-02-25T04:12:50.000Z",
  "computedAt": "2026-02-25T04:12:50.000Z",
  "dataSource": "cached",
  "scoreFreshness": 0.85,
  "freeTier": true,
  "freeQueriesRemainingToday": 9
}

score 的范围是 0–100。confidence 反映有多少链上数据为评分提供依据。dataSource 为 live、cached 或 unavailable，表示评分是刚刚计算的、从缓存返回的，还是无法获取链上数据。拥有更多 USDC 交易历史且身份经过验证的钱包，评分会更高。

在你自己的 README 中嵌入实时评分徽章：

![Agent Score](https://djdagentscore.dev/v1/badge/0x3E4Ef1f774857C69E33ddDC471e110C7Ac7bB528.svg)

查看任意钱包的个人资料页：djdagentscore.dev/agent/{wallet}

---

你可以用它做什么

• 在付费 x402 路由运行前，拒绝信任度低的付款方。
• 在你的 Agent 发送 USDC 或分配工作前，为钱包评分。
• 注册你自己的 Agent，为其钱包添加身份元数据和公开资料。
• 需要更深入的历史记录、完整性信号、评级或强制刷新的时候，使用付费端点。
• 通过评级、欺诈报告、争议和 DJD Forensics 数据流，事后调查问题。

治理层，先从一个切入点着手

DJD 正在构建付费 Agent 商业活动的治理基础设施，但首要任务范围更窄，也更容易采用：阻止不良钱包访问付费路由。

x402 服务提供商——根据付款方信誉控制付费路由。这是最明确的问题，也是最容易的集成路径。

Agent 开发者——在你的 Agent 发送资金、接受请求或参与付费交互前，为钱包评分。

目录和协议——为钱包资料、徽章和访问策略添加公开信任层。

在 Agent 交互前、过程中和之后

• 资金流转前——为钱包评分、控制 x402 路由，并检查钱包是否具备身份和认证背景信息。
• 工作进行时——为活跃关系和付费端点添加监控、Webhook 警报和钱包元数据。
• 发生问题后——记录评级、欺诈报告、争议和取证时间线，让不良交互成为可重复利用的治理数据。

路线图：governance-roadmap.md

---

选择适合你的路径

路径	用途	安装 / 文档
x402 中间件	为付费 Hono 路由进行首次集成的最佳选择	npm：x402-agent-score · 参考示例
REST API	在转账前为钱包评分的最快方式	API 文档
TypeScript SDK	类型安全的 JS/TS 集成	npm：djd-agent-score
MCP 服务	用于 Claude、Cursor、Windsurf、Codex 或任何 MCP 客户端	npm：djd-agent-score-mcp

---

注册你的 Agent

免费发布钱包元数据，为你的个人资料和评分补充身份信息。

curl -X POST https://djdagentscore.dev/v1/agent/register \
  -H 'Content-Type: application/json' \
  -d '{
    "wallet": "0xYourAgentWallet",
    "name": "My Agent",
    "description": "What your agent does",
    "github_url": "https://github.com/you/your-agent",
    "website_url": "https://your-agent.com"
  }'

---

3 行代码完成集成

JavaScript

// Free tier: 10 calls/day, no payment needed
const response = await fetch(
  "https://djdagentscore.dev/v1/score/basic?wallet=" + agentWallet
);
const { score, tier, confidence } = await response.json();

// Gate interactions based on trust
if (score < 50 || confidence < 0.3) {
  console.log("Wallet has insufficient reputation. Declining interaction.");
  return;
}

// Proceed with transaction

Python

import requests

resp = requests.get(
    "https://djdagentscore.dev/v1/score/basic",
    params={"wallet": agent_wallet}
)
data = resp.json()

if data["score"] >= 75 and data["confidence"] >= 0.5:
    # Trusted wallet, proceed
    execute_transaction(agent_wallet)
else:
    # Require additional verification
    flag_for_review(agent_wallet)

curl（使用 x402 的付费端点）

# Full score breakdown for production checks
# x402-compatible clients attach the payment header automatically
curl "https://djdagentscore.dev/v1/score/full?wallet=0x…" \
  -H "X-PAYMENT: <payment_proof>"

---

评分机制

模型 v2.5.0 — 智能评分飞轮。根据总体统计数据自适应调整维度分界点。根据结果学习维度权重。分析评分轨迹（速度、动量、方向）。通过置信度加权的平滑处理提升评分稳定性。百分位排名。

系统会根据钱包在 Base 上的 USDC 交易历史，从五个加权维度评估每个钱包：

维度	基础权重	衡量内容
支付可靠性	30%	在 Base 上的交易历史和一致性
经济可行性	25%	USDC 活动反映的财务健康信号
身份	20%	可验证的身份标记（Basename、GitHub、注册信息、Insumer 代币门控）
行为	15%	交易时间模式和异常检测
能力	10%	已验证的服务交付和生态参与度

维度权重会根据结果相关性数据随时间自适应调整——更能预测钱包真实行为的维度将获得更高的有效权重。

评分等级： 精英（90+）· 可信（75–89）· 已建立（50–74）· 新兴（25–49）· 未验证（0–24）。等级阈值会根据结果校准数据自动调整。

评分引擎使用 EIP-3009 AuthorizationUsed 事件，在链上索引 x402 结算记录。使用 x402 支付服务的 Agent 会积累可验证的支付历史，这些记录会直接计入评分。Agent 通过 x402 进行的交易越多，其声誉就越有参考价值。

自适应评分： v2.5 飞轮会让评分随时间变得更智能。基于总体数据得出的分界点，确保维度评分能够反映钱包在生态系统中的相对位置。评分轨迹分析会根据钱包声誉是在提升还是下降，应用 ±5 分的调整值。置信度加权的平滑处理可避免已建立的评分因有限的新数据而大幅波动。

完整性机制： Sybil 检测、刷分检测和欺诈报告惩罚会以乘法方式应用。评分缓存 1 小时，并在后台为活跃钱包刷新。

---

API 参考

免费端点

端点	方法	描述
/v1/score/basic?wallet=0x…	GET	分数、等级、置信度。每天可免费调用 10 次。
/v1/score/erc8004?wallet=0x…	GET	兼容 ERC-8004 的声誉文档，包含分数、身份、认证和发布状态。
/v1/certification/readiness?wallet=0x…	GET	检查钱包是否可以申请认证、查看阻碍因素，并在付费前了解下一步操作。
/v1/certification/review	GET / POST	提交认证审核请求，或查看钱包的最新审核状态。
/v1/certification/directory?limit=&tier=&search=&sort=	GET	活跃认证的公开目录，包含分数背景、信任链接以及搜索／排序筛选条件。
/directory	GET	可信端点目录页面，可在浏览器中浏览已认证的 Agent。
/v1/agent/register	POST	注册你的钱包。身份奖励 +10 分。
/v1/score/compute	POST	将分数计算加入后台队列，并立即返回 jobId。
/v1/score/job/:jobId	GET	轮询异步任务状态（pending → complete）。
/v1/leaderboard	GET	按分数排名的钱包榜单。
/v1/certification/:wallet	GET	检查认证状态。
/agent/{wallet}	GET	个人资料页面（HTML）。
/v1/badge/{wallet}.svg	GET	可嵌入的 SVG 分数徽章。
/health	GET	服务健康状况和索引器状态。

付费端点（Base 上的 x402 USDC）

端点	方法	价格	描述
/v1/score/full?wallet=0x…	GET	$0.10	各维度分数、原始数据、历史记录和欺诈标记
/v1/score/evaluator?wallet=0x…	GET	$0.35	使用分数、认证、风险和市场信号的 ERC-8183 评估器原型
/v1/score/refresh?wallet=0x…	GET	$0.25	强制实时重新计算（绕过 1 小时缓存）
/v1/score/history?wallet=0x…	GET	$0.15	包含趋势分析的历史分数数据
/v1/report	POST	$0.02	提交针对钱包的欺诈／不当行为举报
/v1/data/fraud/blacklist?wallet=0x…	GET	$0.05	检查钱包是否在欺诈黑名单中
/v1/certification/apply	POST	$99.00	申请认证 Agent 徽章（年费）

API 密钥访问

如需高频使用且不想逐个请求通过 x402 付款，可使用 API 密钥。使用 Authorization: Bearer djd_live_… 进行身份验证——请求次数将计入月度配额，而无需逐次付款。

没有有效的付款凭证或 API 密钥时，付费端点会返回 402 Payment Required。请在 X-PAYMENT 标头中附上付款凭证，或使用 API 密钥。任何兼容 x402 的客户端都可自动处理付款。了解 x402 付款的运作方式 →

---

需要试点方案？

如果你想在生产环境中使用 DJD Agent Score，并希望获得有关起始分数阈值或推出策略的建议，请发送邮件至 [email protected]。

---

举报欺诈

举报从事不当行为的钱包。每次举报收费 $0.02，以防止垃圾举报。经核实的举报会导致分数扣减。

curl -X POST https://djdagentscore.dev/v1/report \
  -H 'Content-Type: application/json' \
  -H 'X-PAYMENT: <payment_proof>' \
  -d '{
    "target": "0xSuspiciousWallet",
    "reporter": "0xYourWallet",
    "reason": "payment_fraud",
    "details": "Agent accepted payment but never delivered the service."
  }'

原因：failed_delivery · payment_fraud · impersonation · malicious_behavior · other

---

本地开发

git clone https://github.com/jacobsd32-cpu/djdagentscore
cd djdagentscore
npm install
npm run dev

需要 Node.js v22。npm run dev 会运行旧版组合式运行时。服务将在 http://localhost:3000 启动。

如需单独运行拆分后的运行时：

npm run dev:api
npm run dev:worker

构建后也可使用生产风格的入口点：

npm run start:api
npm run start:worker

运行时拓扑

• src/app.ts 构建共享的 Hono 应用：路由、中间件、计费和 x402。
• src/api.ts 仅运行 HTTP API。
• src/worker.ts 运行索引器、刷新器、异常检测、Webhook 投递和发布任务。
• src/index.ts 是旧版合并运行时，仍是默认的 npm run dev / npm start 路径。

推荐的部署方式：

• API 进程：npm run start:api
• Worker 进程：npm run start:worker
• 合并运行时：仅用于本地开发或向后兼容的单进程部署

当前生产环境说明：

• 在存储方式变更之前，Fly 部署应继续使用合并运行时。
• 此应用仍在 Fly 卷上使用 SQLite，而这种存储模式会阻碍 API 和 Worker 机器安全地拆分并使用同一个数据库文件。

部署冒烟检查

部署工作流现在会验证 /health 是否正常运行，以及响应应用报告的运行时模式和预期的发布 SHA。 管理端 /health 还会公开 Worker 作业启用状态，以及有关 GitHub 验证和 ERC-8004 发布就绪状态的集成警告。 对于 GitHub Actions，生产冒烟验证可以使用 DJD_ADMIN_KEY 或旧版 ADMIN_KEY 密钥；预览环境会优先使用 FLY_PREVIEW_ADMIN_KEY，否则回退到 DJD_ADMIN_KEY / ADMIN_KEY。

DJD_HEALTHCHECK_URL=https://djdagentscore.dev/health \
DJD_EXPECT_RUNTIME_MODE=combined \
DJD_EXPECT_RELEASE_SHA=<git_sha> \
DJD_ADMIN_KEY=<admin_key> \
npm run smoke:deploy

预览部署通道

现在，codex/runtime-split-entrypoints 可以通过 .github/workflows/fly-preview.yml 部署到非生产 Fly 预览应用。

• 必需的 GitHub 变量：FLY_PREVIEW_APP
• 可选的 GitHub 变量：FLY_PREVIEW_PUBLIC_BASE_URL
• 可选的 GitHub 密钥：FLY_PREVIEW_API_TOKEN（如果现有的 FLY_API_TOKEN 仅限生产应用使用，请使用此项）
• 可选的 GitHub 密钥：FLY_PREVIEW_ADMIN_KEY（依次回退到 DJD_ADMIN_KEY、ADMIN_KEY）

如果未设置 FLY_PREVIEW_PUBLIC_BASE_URL，工作流默认使用 https://<FLY_PREVIEW_APP>.fly.dev。 预览 Fly 配置会继承 fly.toml 中的 PAY_TO 和其他共享环境变量，并自动将 CORS_ORIGINS 设为预览公共基础 URL，因此全新的预览应用无需单独的 CORS 密钥即可启动。 预览部署使用 Fly 的 immediate 策略，因为预览应用是挂载了一个卷的单机 SQLite 服务；在此场景下，原地更新比滚动替换更可靠。

预览应用应独立于生产环境配置，并应拥有自己的 Fly 挂载卷，名称为 djd_agent_score_data，因为此服务仍使用单个 SQLite 文件运行。

使用 npm run audit:promotion，在晋级前检查 src/ 和 index.html 中可能导致预览环境不安全的硬编码生产 URL。 使用 npm run render:fly-config -- --app <preview-app> --public-base-url <preview-url> --output .fly/preview.toml，从 fly.toml 生成适用于预览环境的 Fly 配置，而不修改仓库中的生产配置。

环境变量

变量	默认值	描述
PORT	3000	HTTP 端口
DJD_RUNTIME_MODE	combined	要启动的已构建入口：combined、api 或 worker
DJD_RELEASE_SHA	unset	烘焙到容器镜像中并通过 /health 公开的发布提交
DJD_BUILD_TIMESTAMP	unset	烘焙到容器镜像中并通过 /health 公开的 UTC 构建时间戳
PAY_TO	0x3E4Ef1f774857C69E33ddDC471e110C7Ac7bB528	x402 支付的 USDC 收款方
FACILITATOR_URL	https://x402.org/facilitator	x402 协调器端点
BASE_RPC_URL	https://base-mainnet.public.blastapi.io	Base RPC（推荐使用 BlastAPI）
GITHUB_TOKEN	unset	可选的 GitHub API 令牌；缺失时，管理端 /health 会报告未认证模式，并使用每小时 60 次请求的备用限额
ENABLE_BLOCKCHAIN_INDEXER	true	在 worker/combined 运行时启用 x402 结算索引
ENABLE_USDC_INDEXER	true	在 worker/combined 运行时启用 USDC 转账索引
ENABLE_HOURLY_REFRESH	true	在 worker/combined 运行时启用每小时评分刷新
PUBLISHER_PRIVATE_KEY	unset	用于 ERC-8004 发布的可选 Base 钱包密钥；缺失时，管理端 /health 会报告发布功能已禁用
DJD_HEALTHCHECK_URL	https://djdagentscore.dev/health	npm run smoke:deploy 使用的健康检查端点
DJD_EXPECT_RUNTIME_MODE	combined	部署冒烟验证的预期运行时模式
DJD_EXPECT_RELEASE_SHA	unset	部署冒烟验证的预期发布 SHA
DJD_ADMIN_KEY	unset	可选管理密钥，供部署冒烟验证检查详细运行时健康状态

---

技术说明

技术栈： Hono + SQLite + viem，部署在 Fly.io 上。完整架构文档见 docs/architecture.md。

区块链索引器： 每 12 秒轮询 Base USDC，获取 AuthorizationUsed 和 Transfer 事件。两层过滤（EIP-3009 事件 + 1 美元 USDC 金额上限）可将 x402 结算与常规 DeFi 活动区分开来。自适应分块大小可应对 BlastAPI 的 20k 结果上限。

数据库： SQLite，使用 DELETE 日志模式（因其兼容 Fly.io 网络挂载卷而选择，而非 WAL）。31 张表涵盖评分、历史记录、欺诈报告、注册信息、查询日志、索引器状态、API 密钥、webhook、认证、作业统计、结果校准和异常检测。

RPC 提供方： 默认使用 BlastAPI 公共 Base 端点。进行大量索引时，请通过 BASE_RPC_URL 使用专用提供方。避免使用 publicnode.com（会拒绝范围为 10k 个区块的 eth_getLogs 请求）。

ERC-8004： /v1/score/erc8004 提供 ERC-8004（AI Agent 注册表）兼容性；配置后，链上发布作业会将高置信度的 DJD 评分写入信誉注册表。

评分缓存： 缓存 1 小时。后台每批刷新最多 50 个已过期评分。使用 /v1/score/refresh（0.25 美元）强制重新计算。管理端刷新接口会使所有缓存评分过期，以便在模型更新后触发整个生态系统重新评分。

自动重新校准： 系统根据真实结果数据持续调整评分阈值，形成预测信任度与实际钱包行为之间的反馈闭环。

Agent 自动发现

兼容 x402 的 Agent 可以自动发现所有 DJD 端点：

curl https://djdagentscore.dev/.well-known/x402

返回一份机器可读清单，列出每个端点、其价格、输入架构和集成选项。

x402 支付的工作方式

x402 是一种基于 HTTP 402 构建的开放支付协议。访问付费端点时如果未付款，系统会返回一条包含支付说明（金额、收款方、网络）的 402 响应。你的 x402 客户端会在 Base 上签署一笔 USDC 支付，将支付凭证附加到 X-PAYMENT，然后重新发送请求。只需额外往返一次，客户端库会自动处理。

无需 API 密钥。无需订阅。无需账户。按请求进行小额支付。

---

License

MIT

---

Built by DJD · Powered by x402 · Running on Base