{"openapi":"3.1.0","info":{"title":"Telaro Public API","version":"0.1.0","description":"Public REST API for the Telaro protocol. Read-only; no authentication. CORS enabled. Use the typed `TelaroApi` client from `@telaro/sdk` for the easiest integration.","contact":{"name":"Telaro","url":"https://telaro.xyz"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://www.telaro.xyz","description":"Production"}],"paths":{"/api/health":{"get":{"summary":"Liveness","tags":["meta"],"responses":{"200":{"description":"Service info","content":{"application/json":{"schema":{"type":"object","required":["ok","service","version","network"],"properties":{"ok":{"type":"boolean"},"service":{"type":"string"},"version":{"type":"string"},"network":{"type":"string"}}}}}}}}},"/api/agents":{"get":{"summary":"List bonded agents","tags":["agents"],"parameters":[{"name":"framework","in":"query","schema":{"type":"string"}},{"name":"minBond","in":"query","schema":{"type":"string"},"description":"Atomic USDC base units, as decimal string"},{"name":"minScore","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":500}}],"responses":{"200":{"description":"List of agents sorted by score desc","content":{"application/json":{"schema":{"type":"object","required":["count","agents"],"properties":{"count":{"type":"integer"},"agents":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}}}}}}}}},"/api/agent/{pubkey}":{"get":{"summary":"Single agent full detail","tags":["agents"],"parameters":[{"name":"pubkey","in":"path","required":true,"schema":{"type":"string"},"description":"Agent PDA pubkey (base58)"}],"responses":{"200":{"description":"Identity + score + bond + last 100 actions + claims + 30d score series","content":{"application/json":{"schema":{"type":"object","required":["agent","actions","claims","score_series"],"properties":{"agent":{"allOf":[{"$ref":"#/components/schemas/Agent"},{"type":"object","properties":{"image_url":{"type":"string","format":"uri"}}}]},"actions":{"type":"array","items":{"$ref":"#/components/schemas/Action"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"score_series":{"type":"array","items":{"type":"object","properties":{"ts":{"type":"integer"},"score":{"type":"integer"}}}}}}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"agent_not_found"}}}}}}}}},"/api/leaderboard":{"get":{"summary":"Top-N + ecosystem stats","tags":["agents"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Ecosystem-wide stats + top agents","content":{"application/json":{"schema":{"type":"object","required":["ecosystem","top"],"properties":{"ecosystem":{"$ref":"#/components/schemas/Ecosystem"},"top":{"type":"array","items":{"type":"object","properties":{"pubkey":{"type":"string"},"name":{"type":"string"},"framework":{"type":"string"},"score":{"type":"integer"},"bond_atomic":{"type":"string"},"bond_human":{"type":"number"},"action_count":{"type":"integer"},"success_rate":{"type":"number"}}}}}}}}}}}},"/api/card/{pubkey}.png":{"get":{"summary":"Dynamic Trust Card PNG (1200×630, suitable as NFT image_url)","tags":["assets"],"parameters":[{"name":"pubkey","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"PNG image","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}}}}}},"components":{"schemas":{"Agent":{"type":"object","required":["pubkey","controller","framework","name","score","score_tier","bond_atomic","bond_human","action_count","success_count","failed_count","disputed_count","success_rate","bonded_since","last_action_at","value_handled_30d","open_claims","frozen","network"],"properties":{"pubkey":{"type":"string","description":"Agent PDA, base58 Solana pubkey"},"controller":{"type":"string","description":"Builder pubkey that controls this agent"},"framework":{"type":"string","enum":["sendai","eliza","goat","buzz","voltr","custom"]},"name":{"type":"string"},"score":{"type":"integer","minimum":0,"maximum":1000},"score_tier":{"type":"string","enum":["high","medium","low"]},"bond_atomic":{"type":"string","description":"USDC base units (6 decimals), as decimal string"},"bond_human":{"type":"number","description":"Human USDC amount"},"action_count":{"type":"integer"},"success_count":{"type":"integer"},"failed_count":{"type":"integer"},"disputed_count":{"type":"integer"},"success_rate":{"type":"number","minimum":0,"maximum":1},"bonded_since":{"type":"integer","description":"Unix epoch seconds"},"last_action_at":{"type":"integer","description":"Unix epoch seconds"},"value_handled_30d":{"type":"string","description":"USDC base units, decimal string"},"open_claims":{"type":"integer"},"frozen":{"type":"boolean"},"network":{"type":"string","enum":["devnet","mainnet-beta"]}}},"Action":{"type":"object","required":["signature","kind","kind_label","outcome","outcome_label","value_atomic","value_human","slot","ts"],"properties":{"signature":{"type":"string"},"kind":{"type":"integer"},"kind_label":{"type":"string"},"outcome":{"type":"integer","minimum":0,"maximum":2},"outcome_label":{"type":"string","enum":["success","failed","disputed"]},"value_atomic":{"type":"string"},"value_human":{"type":"number"},"slot":{"type":"integer"},"ts":{"type":"integer"}}},"Claim":{"type":"object","properties":{"pubkey":{"type":"string"},"claimer":{"type":"string"},"claimed_atomic":{"type":"string"},"claimed_human":{"type":"number"},"evidence_uri":{"type":"string"},"status":{"type":"string","enum":["open","accepted","auto-accepted","rejected"]},"created_at":{"type":"integer"},"deadline":{"type":"integer"},"resolved_at":{"type":"integer"},"paid_out":{"type":"number"}}},"Ecosystem":{"type":"object","properties":{"bond_tvl_atomic":{"type":"string"},"bond_tvl_human":{"type":"number"},"agent_count":{"type":"integer"},"framework_count":{"type":"integer"},"total_actions":{"type":"integer"},"dispute_rate":{"type":"number"},"value_handled_30d":{"type":"number"},"open_claims":{"type":"integer"},"paid_out_total":{"type":"number"}}}}},"tags":[{"name":"meta","description":"Service metadata"},{"name":"agents","description":"Read agents and ecosystem stats"},{"name":"assets","description":"Dynamic visual assets (Trust Card PNGs)"}]}