{"openapi":"3.0.3","info":{"title":"Helixa V2 API","version":"2.0.0","description":"Onchain identity and reputation for AI agents. Register identities, set personality traits, build Cred Scores, and verify agents via API with SIWA auth. Platform fees are currently waived.","contact":{"url":"https://helixa.xyz"}},"servers":[{"url":"https://api.helixa.xyz","description":"Production (Base Mainnet)"}],"paths":{"/api/v2/stats":{"get":{"summary":"Protocol statistics","description":"Returns aggregate Helixa protocol stats: total agents, mints, verifications, cred distribution.","responses":{"200":{"description":"Protocol stats object","content":{"application/json":{"schema":{"type":"object","properties":{"totalAgents":{"type":"integer"},"totalVerified":{"type":"integer"},"totalSoulLocked":{"type":"integer"},"totalHandshakes":{"type":"integer"},"avgCredScore":{"type":"number"}}}}}}}}},"/api/v2/agents":{"get":{"summary":"List or search agents","description":"Returns registered Helixa agents. Use search param to filter by name or address.","parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"Search by agent name or wallet address"},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Array of agent objects"}}}},"/api/v2/agent/{id}":{"get":{"summary":"Get agent by token ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Agent object with full personality, traits, narrative, and cred score"}}}},"/api/v2/agent/{address}/cred":{"get":{"summary":"Check agent Cred score","description":"Returns the Cred score, tier, and factor breakdown for an agent by wallet address.","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Agent wallet address (0x...)"}],"responses":{"200":{"description":"Cred score breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"credScore":{"type":"number"},"tier":{"type":"string","enum":["basic","verified","trusted","elite","legendary"]},"factors":{"type":"object"}}}}}},"404":{"description":"Agent not found"}}}},"/api/v2/agent/{address}/session-outcome":{"post":{"summary":"Report a session outcome","description":"Report the outcome of an agent interaction session. Requires API key.","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Agent wallet address"}],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["outcome"],"properties":{"outcome":{"type":"string","enum":["success","failure","partial"]},"details":{"type":"string"},"sessionId":{"type":"string"},"duration":{"type":"integer","description":"Session duration in seconds"}}}}}},"responses":{"200":{"description":"Outcome recorded"},"401":{"description":"Missing or invalid API key"}}}},"/api/v2/mint":{"post":{"summary":"Register a new agent identity","description":"Requires SIWA authentication. Creates onchain identity with name, framework, personality, narrative, and traits. No platform fee required right now.","security":[{"siwa":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","framework"],"properties":{"name":{"type":"string","description":"Agent display name"},"framework":{"type":"string","description":"Agent framework (e.g. openclaw, elizaos, agentkit, langchain)"},"soulbound":{"type":"boolean","description":"Lock identity to this wallet (non-transferable)"},"personality":{"type":"object","properties":{"quirks":{"type":"string"},"communicationStyle":{"type":"string"},"values":{"type":"string"},"humor":{"type":"string"},"riskTolerance":{"type":"integer","minimum":1,"maximum":10},"autonomyLevel":{"type":"integer","minimum":1,"maximum":10}}},"narrative":{"type":"object","properties":{"origin":{"type":"string"},"mission":{"type":"string"},"lore":{"type":"string"}}},"referralCode":{"type":"string","description":"Referral code from another agent"}}}}}},"responses":{"201":{"description":"Agent registered successfully"},"401":{"description":"Invalid SIWA authentication"},"402":{"description":"Payment required (when pricing is active)"}}}},"/api/v2/agent/{id}/personality":{"put":{"summary":"Update agent personality","security":[{"siwa":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Personality updated"}}}},"/api/v2/agent/{id}/verify":{"post":{"summary":"Verify agent identity","security":[{"siwa":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Agent verified, Cred Score boosted"}}}},"/api/v2/metadata/{id}":{"get":{"summary":"OpenSea-compatible NFT metadata","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"ERC-721 metadata JSON"}}}},"/api/v2/leaderboard":{"get":{"summary":"Agent leaderboard by Cred Score or Points","parameters":[{"name":"sort","in":"query","schema":{"type":"string","enum":["cred","points"],"default":"cred"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Sorted agent list"}}}}},"components":{"securitySchemes":{"siwa":{"type":"apiKey","in":"header","name":"Authorization","description":"SIWA token: address:timestamp:signature (agent signs message with wallet key)"},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for reporting session outcomes"}}}}