{"openapi":"3.0.3","info":{"title":"KYA API","version":"0.1.0","description":"Know Your Agent — attestation aggregation service."},"components":{"securitySchemes":{"AgentSignature":{"type":"apiKey","in":"header","name":"x-agent-signature","description":"EIP-712 signature of the Action message (see /api-docs)."}},"schemas":{}},"paths":{"/healthz":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/readyz":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/agents/{identifier}/attestations":{"get":{"summary":"列出某 agent 的所有 attestation（identifier 支持 0x 地址或 did:pkh）；type 不传或 staking 时会按需到 AWP /v2 刷新缓存","tags":["public"],"parameters":[{"schema":{"type":"string","enum":["twitter_claim","telegram_claim","email_claim","staking","kyc"]},"in":"query","name":"type","required":false},{"schema":{"type":"string","enum":["pending","active","expired","revoked"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"path","name":"identifier","required":true,"description":"Agent 地址（0x...）或 did:pkh:eip155:<chainId>:<addr>"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/agents/{identifier}/attestations/reveal":{"post":{"summary":"凭 agent EIP-712 签名换出未脱敏 metadata（默认 GET /attestations 隐藏 email/country）","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true,"description":"Agent 地址（0x...）或 did:pkh:eip155:<chainId>:<addr>"},{"schema":{"type":"string"},"in":"header","name":"x-agent-signature","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-timestamp","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-nonce","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/agents/{identifier}/deposit-address":{"get":{"summary":"获取或生成 agent 的 KYA reward deposit address","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/agents/{identifier}/binding":{"get":{"summary":"解析 agent 在 AWPRegistry 上的 binding（实时上游查询）","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true,"description":"0x 地址或 did:pkh:eip155:<chainId>:<addr>"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/agents/{identifier}/worknet-view":{"get":{"summary":"agent 的 worknet 资格视图（链上事实直出，给 worknet 准入用）","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true,"description":"Agent 地址（0x...）或 did:pkh:eip155:<chainId>:<addr>"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/agents":{"get":{"summary":"批量查询 agent 的 worknet 资格视图（最多 100 个）","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"addresses","required":true,"description":"逗号分隔的 0x 地址列表，最多 100 个"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/agents/lookup":{"get":{"summary":"通过 Twitter handle 反向查找已 active 认领的 agent 地址","tags":["public"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":15},"in":"query","name":"handle","required":true,"description":"Twitter / X handle，可带或不带 @（不区分大小写）"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/owners/{identifier}/agents":{"get":{"summary":"列出某 owner 名下绑定的 agent（identifier 支持 0x 地址或 did:pkh）","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true,"description":"Owner 地址（0x...）或 did:pkh:eip155:<chainId>:<addr>"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/worknets":{"get":{"summary":"List active worknets KYA can match agents into","tags":["public"],"responses":{"200":{"description":"Default Response"}}}},"/v1/worknets/{worknetId}/agents":{"get":{"summary":"列出指定 worknet 下的所有 agent（带 KYC / Twitter 摘要，供 worknet builder 做 sybil 过滤）","tags":["public"],"parameters":[{"schema":{"type":"string","enum":["pending","active","expired","revoked"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["0","1"]},"in":"query","name":"refresh","required":false,"description":"默认 0；设为 1 时对返回名单内每个 agent（最多 50 并发）触发一次 AWP /v2 按需刷新，确保 staking_status 新鲜。热门 worknet 不要默认开。"},{"schema":{"type":"string"},"in":"path","name":"worknetId","required":true,"description":"worknetId 数字串，例如 845300000002，或 urn:awp:worknet:845300000002"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/resolve":{"post":{"summary":"反解任意 KYA 标识符（地址 / DID / URN）→ canonical 形式","tags":["public"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["identifier"],"properties":{"identifier":{"type":"string"}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/metrics":{"get":{"summary":"全网聚合指标：已验证 agent 总数、各类 attestation 计数、AWP 累计质押量等","tags":["public"],"responses":{"200":{"description":"Default Response"}}}},"/v1/pool/overview":{"get":{"summary":"Delegated staking 池总览：TVL、已用、利用率、APY、奖励切分","tags":["public"],"responses":{"200":{"description":"Default Response"}}}},"/v1/kya/sponsors":{"get":{"summary":"KYA allocator proxy 地址（兼容 sponsor 语义）","tags":["public"],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/{identifier}/delegations":{"get":{"summary":"查询某地址作为 agent 时获得的代质押列表（sponsor ≠ agent 的 staking attestation）","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true,"description":"Agent 地址（0x...）或 did:pkh:eip155:<chainId>:<addr>"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/providers/{identifier}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/providers/{identifier}/positions":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/providers/{identifier}/rewards":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/providers/intent":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/providers/{identifier}/stats":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/providers/{identifier}/capacity":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/providers/{identifier}/onboarding":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/services/staking/request":{"post":{"summary":"入队委托质押请求","tags":["services"],"description":"agent 对 (worknet, amount) 签 EIP-712 → KYA 入队 → matchingEngine 在 provider 名下走 KyaAllocatorProxy.allocate()。","parameters":[{"schema":{"type":"string"},"in":"header","name":"x-agent-signature","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-timestamp","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-nonce","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/services/staking/requests":{"get":{"summary":"查询某 agent 的全部委托质押请求","tags":["services"],"responses":{"200":{"description":"Default Response"}}}},"/v1/agents/{identifier}/airdrop":{"get":{"summary":"查询某 agent 在 KYA verification airdrop 中的应得金额（lifetime）；?refresh=1 强制重算","tags":["public"],"parameters":[{"schema":{"type":"string","enum":["1","0","true","false"]},"in":"query","name":"refresh","required":false},{"schema":{"type":"string"},"in":"path","name":"identifier","required":true,"description":"Agent 地址（0x...）或 did:pkh:eip155:<chainId>:<addr>"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/agents/{identifier}/airdrop/voucher":{"get":{"summary":"签发一张 cumulative airdrop voucher，agent 自己去 KyaAirdropDistributor.claim() 提走 AWP（自付 gas）","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true,"description":"Agent 地址（0x...）或 did:pkh:eip155:<chainId>:<addr>"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/worknets/{worknetId}/agent-reports":{"post":{"summary":"Worknet owner 提交本 worknet 在某 epoch 的 agent 工作报告批次（EIP-712 签名）","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"worknetId","required":true}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"查询某 worknet 的 agent 工作报告（按 agent / epoch 过滤、分页）","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"worknetId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/worknet-agent-reports/{reportId}":{"get":{"summary":"按 report_id 拉取 batch 原文 + 签名，第三方可独立复算 batch_hash 验签","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"reportId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/agents/{identifier}/reports":{"get":{"summary":"反查 agent 在所有（或指定）worknet 的工作报告","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true,"description":"agent 地址（0x...）或 did:pkh:eip155:<chainId>:<addr>"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/epochs/current":{"get":{"summary":"当前 AWP epoch 元信息（时间窗 + phase + 来源），用于 owner 自动化对账","tags":["public"],"responses":{"200":{"description":"Default Response"}}}},"/v1/epochs/{epochId}":{"get":{"summary":"指定 epoch 的时间窗 + phase","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"epochId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/agents/{address}/epoch-airdrops":{"get":{"summary":"查询 agent 在各 epoch 的 AI 评估奖励（来自 worknet 工作报告）","tags":["public"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"address","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/attestations/twitter/prepare":{"post":{"summary":"申请 Twitter 认领暗号","tags":["twitter"],"description":"agent 钱包签名后获取一次性 nonce 和 claim_text。用户发推时必须包含 claim_text 原文。","parameters":[{"schema":{"type":"string"},"in":"header","name":"x-agent-signature","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-timestamp","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-nonce","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/attestations/twitter/claim":{"post":{"summary":"提交推文 URL 发起认领","tags":["twitter"],"description":"创建 pending 的 twitter_claim attestation；Task B 异步验证。","parameters":[{"schema":{"type":"string"},"in":"header","name":"x-agent-signature","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-timestamp","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-nonce","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/attestations/telegram/prepare":{"post":{"summary":"申请 Telegram 公开频道认领暗号","tags":["telegram"],"description":"agent 钱包签名后获取一次性 nonce 与 claim_text。用户须在公开频道发帖，正文含 claim_text。","parameters":[{"schema":{"type":"string"},"in":"header","name":"x-agent-signature","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-timestamp","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-nonce","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/attestations/telegram/claim":{"post":{"summary":"提交频道消息 URL 发起认领","tags":["telegram"],"description":"创建 pending 的 telegram_claim attestation；social worker 的 Telegram loop 异步校验。","parameters":[{"schema":{"type":"string"},"in":"header","name":"x-agent-signature","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-timestamp","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-nonce","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/attestations/email/prepare":{"post":{"summary":"为 (agent, email) 发送验证码","tags":["email"],"description":"agent 钱包对 action=\"email_prepare\" 签名;后端生成 6 位数字验证码,经 Resend 发往该邮箱。同 (agent, email) 在 cooldown 内重复请求将返回 429。","parameters":[{"schema":{"type":"string"},"in":"header","name":"x-agent-signature","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-timestamp","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-nonce","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/attestations/email/confirm":{"post":{"summary":"提交验证码完成邮箱认领","tags":["email"],"description":"agent 钱包对 action=\"email_confirm\" 签名;比对 prepare 阶段下发的 6 位验证码,通过后写入 active 的 email_claim attestation。","parameters":[{"schema":{"type":"string"},"in":"header","name":"x-agent-signature","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-timestamp","required":true},{"schema":{"type":"string"},"in":"header","name":"x-agent-nonce","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/internal/attestations":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/attestations/{id}/finalize":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/internal/twitter/pending":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/internal/telegram/pending":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/internal/staking/known-pairs":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/internal/staking/sweep-expired":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/signature/consume":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/attestations/kyc/finalize":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/matching/run":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/distribution/sweep":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/distribution/distribute":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/distribution/forward":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/providers/state-change":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/rewards/incoming":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/agents/recipient-change":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/deposit-addresses":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/internal/worknets":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/internal/worknets/upsert":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/airdrops/recompute":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/airdrops/eval-epoch":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/airdrops/dashboard":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/airdrops/claim/preview":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/internal/airdrops/claim/execute":{"post":{"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://kya.link"}],"tags":[{"name":"public","description":"公开查询接口"},{"name":"twitter","description":"Twitter 认领相关"},{"name":"telegram","description":"Telegram 公开频道认领相关"},{"name":"email","description":"邮箱钱包绑定验证(类 Twitter 模式)"}]}