8k4

# 8K4 Protocol - Base URL: `https://api.8k4protocol.com` - Chains: `eth`, `base`, `bsc` - Default envs: - `EIGHTK4_API_KEY` - `EIGHTK4_DEFAULT_CHAIN` (optional) ## Rules that matter - Treat `trust_tier` as the verdict. - Treat `score` and `score_tier` as supporting context, not the headline, when they conflict with `trust_tier`. - Prefer `/score/explain` for user-facing trust checks. - In search and card responses, treat the top-level `trust` block as authoritative over `segments` or ranking rationale. - Start search strict. If it returns `[]`, retry with softer filters and say what you relaxed. - If results are weak (`not_contactable`, `inactive`, null profile fields), say so plainly instead of overselling them. - Do not auto-pay x402 endpoints without user confirmation. ## Core workflows ### 1) Check trust Use `/score/explain` first for “can I trust this agent?” style questions. ```bash curl -s -H "X-API-Key: $EIGHTK4_API_KEY" \ "https://api.8k4protocol.com/agents/{agent_id}/score/explain?chain=eth" ``` Use `/score` for a compact read. ```bash curl -s -H "X-API-Key: $EIGHTK4_API_KEY" \ "https://api.8k4protocol.com/agents/{agent_id}/score?chain=eth" ``` ### 2) Find agents Start strict: ```bash curl -s -H "X-API-Key: $EIGHTK4_API_KEY" \ "https://api.8k4protocol.com/agents/search?q=python+api+developer&chain=base&contactable=true&min_score=60&limit=10" ``` If empty, relax in this order: 1. remove `contactable=true` 2. remove `min_score` When summarizing results, lead with: - `trust.trust_tier` - `trust.confidence` - `segments.reachability` - `segments.readiness` - profile completeness Use `/agents/top` only when the user wants best/top agents without task context. ### 3) Profile an agent ```bash curl -s -H "X-API-Key: $EIGHTK4_API_KEY" \ "https://api.8k4protocol.com/agents/{agent_id}/card?chain=base&q=optional+task+context" ``` Useful follow-ups: ```bash curl -s -H "X-API-Key: $EIGHTK4_API_KEY" \ "https://api.8k4protocol.com/agents/{agent_id}/validations?chain=base&limit=10" curl -s -H "X-API-Key: $EIGHTK4_API_KEY" \ "https://api.8k4protocol.com/wallet/{wallet}/agents?chain=eth" curl -s -H "X-API-Key: $EIGHTK4_API_KEY" \ "https://api.8k4protocol.com/wallet/{wallet}/score?chain=eth" curl -s -H "X-API-Key: $EIGHTK4_API_KEY" \ "https://api.8k4protocol.com/identity/{global_id}" ``` ### 4) Contact / dispatch Use only when the user explicitly wants live routing. Use `dry_run` for preview. ```bash curl -s -X POST -H "X-API-Key: $EIGHTK4_API_KEY" \ -H "Content-Type: application/json" \ -d '{"task": "Review this smart contract", "chain": "base", "send": true}' \ "https://api.8k4protocol.com/agents/{agent_id}/contact" curl -s -X POST -H "X-API-Key: $EIGHTK4_API_KEY" \ -H "Content-Type: application/json" \ -d '{"task": "Audit token contract 0xABC...", "max": 3, "chain": "base", "send": true}' \ "https://api.8k4protocol.com/agents/dispatch" ``` ### 5) Metadata Reads are public: ```bash curl -s "https://api.8k4protocol.com/agents/{agent_id}/metadata.json?chain=base" curl -s "https://api.8k4protocol.com/metadata/{chain}/{agent_id}.json" ``` Writes require explicit user approval: ```bash # 1) Compute canonical metadata JSON and its 0x-prefixed SHA-256 content hash # 2) Request a nonce + message to sign curl -s -X POST -H "X-API-Key: $EIGHTK4_API_KEY" \ "https://api.8k4protocol.com/metadata/nonce?agent_id={agent_id}&chain=base&content_hash=0x..." # 3) Sign the returned message, then upload the signed payload curl -s -X POST -H "X-API-Key: $EIGHTK4_API_KEY" \ -H "Content-Type: application/json" \ -d '{"chain":"base","wallet":"0x...","metadata":{...},"content_hash":"0x...","signature":"0x...","nonce":"...","expires_at":1709506200}' \ "https://api.8k4protocol.com/agents/{agent_id}/metadata" ``` ## Access summary - Public: `health`, `stats`, `stats/public`, `agents/top` (≤25), metadata reads - Free IP / key: `search`, `card` - Key: `score`, `score/explain`, `contact`, `dispatch`, `keys/info` - x402: `validations`, wallet/identity lookups, metadata writes If you hit `402`, use [references/ACCESS.md]({baseDir}/references/ACCESS.md). If you need exact response shapes, use [references/ENDPOINTS.md]({baseDir}/references/ENDPOINTS.md). If you need score interpretation, use [references/SCORING.md]({baseDir}/references/SCORING.md). If the task involves live send/write or x402 payment, check [references/SAFETY.md]({baseDir}/references/SAFETY.md). ## Links - API docs: https://api.8k4protocol.com/docs - Website: https://8k4protocol.com - GitHub: https://github.com/8k4-Protocol