{"openapi":"3.1.0","info":{"title":"Wicked Agent Reputation & Staking Service","description":"ERC-8004-style agent reputation and USDC staking layer. See README for the GET /agents/{wallet}/status contract.","version":"0.1.0"},"paths":{"/agents/{wallet}/nonce":{"get":{"summary":"Get Nonce","operationId":"get_nonce_agents__wallet__nonce_get","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string","title":"Wallet"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NonceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/register":{"post":{"summary":"Register Agent","operationId":"register_agent_agents_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{wallet}/stake":{"post":{"summary":"Stake","operationId":"stake_agents__wallet__stake_post","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string","title":"Wallet"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StakeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{wallet}/unstake":{"post":{"summary":"Unstake","description":"Starts the unbonding period for `amount` of an agent's active stake.\nThe amount stops counting toward tier/reputation immediately (matches\nstandard staking systems: you stop earning the moment you start\nunbonding). It remains slashable until actually withdrawn — see\nslash_agent — so unbonding cannot be used to dodge a pending slash.","operationId":"unstake_agents__wallet__unstake_post","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string","title":"Wallet"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnstakeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnstakeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{wallet}/withdraw":{"post":{"summary":"Withdraw","description":"Pays out every unbonding stake whose cooldown has elapsed, in one\non-chain transfer. Marks rows as withdrawn only after the payout\nactually succeeds — a failed payout leaves them unbonding, safe to\nretry.","operationId":"withdraw_agents__wallet__withdraw_post","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string","title":"Wallet"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{wallet}/slash":{"post":{"summary":"Slash Agent","operationId":"slash_agent_agents__wallet__slash_post","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string","title":"Wallet"}},{"name":"x-admin-api-key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Admin-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlashRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{wallet}/status":{"get":{"summary":"Get Status","operationId":"get_status_agents__wallet__status_get","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string","title":"Wallet"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{wallet}/history":{"get":{"summary":"Get History","operationId":"get_history_agents__wallet__history_get","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string","title":"Wallet"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tiers":{"get":{"summary":"List Tiers","operationId":"list_tiers_tiers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/TierOut"},"type":"array","title":"Response List Tiers Tiers Get"}}}}}}},"/leaderboard":{"get":{"summary":"Leaderboard","description":"Public, unauthenticated. Every agent's current active stake, tier,\nand slash count — the whole point of on-chain reputation is that it's\ncheckable by anyone, not just the wallet in question.","operationId":"leaderboard_leaderboard_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LeaderboardEntry"},"title":"Response Leaderboard Leaderboard Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/query":{"get":{"summary":"Query Agents","description":"Public, unauthenticated. A parameterized filter/sort over the same\nfields /leaderboard exposes -- built as a safe alternative to a raw SQL\nconsole: no query string ever reaches the database, every parameter is\ntyped and validated by FastAPI/pydantic, so there's no injection surface\nand no way to run an expensive ad-hoc query against production.","operationId":"query_agents_agents_query_get","parameters":[{"name":"tier","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tier"}},{"name":"min_stake","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Stake"}},{"name":"max_stake","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Stake"}},{"name":"min_reputation","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Reputation"}},{"name":"max_reputation","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Reputation"}},{"name":"founding_member","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Founding Member"}},{"name":"min_slash_count","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min Slash Count"}},{"name":"max_slash_count","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Slash Count"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","default":"-stake_amount","title":"Sort"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentQueryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{wallet}/statement":{"get":{"summary":"Get Statement","description":"Public. A per-agent 'financial statement' view, but scoped honestly to\nwhat this service actually tracks: it does NOT include WickedAPI call\nvolume or fees paid -- that data lives in a different service this one\nhas no access to. `position` is exact (see the conservation note below);\n`ledger` reuses the same real event rows /history returns, just reshaped\n-- no reconstructed historical tier/score curve, because a stake row's\namount can be split across multiple partial /unstake calls over its life\nand this service doesn't keep a separate amount-over-time audit log, so\na per-event historical score would be more precise-looking than it is\nactually accurate.","operationId":"get_statement_agents__wallet__statement_get","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string","title":"Wallet"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentStatementResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{wallet}/erc8004":{"get":{"summary":"Get Erc8004 Identity","description":"Public. Cross-references this wallet against the open ERC-8004\n(https://eips.ethereum.org/EIPS/eip-8004) Identity + Reputation\nRegistries on the reference deployment -- read-only: we don't write\nfeedback into that registry (yet), this only checks what's already\nthere. `found: false` just means the wallet has never self-registered\nwith ERC-8004, which is expected and common for a young, Draft-stage\nstandard -- it's not an error and doesn't affect this service's own\ntier/score.","operationId":"get_erc8004_identity_agents__wallet__erc8004_get","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string","title":"Wallet"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erc8004Response"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/transparency":{"get":{"summary":"Transparency","description":"Public. What's actually true about custody here: a single CDP-managed\nwallet, not a smart-contract escrow — every stake, slash, and payout is\nstill independently verifiable on-chain by anyone via the explorer link\nbelow, but the service itself has to be trusted to only move funds\nthrough the code paths in this API.","operationId":"transparency_transparency_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransparencyResponse"}}}}}}},"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"AgentQueryResponse":{"properties":{"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"sort":{"type":"string","title":"Sort"},"results":{"items":{"$ref":"#/components/schemas/LeaderboardEntry"},"type":"array","title":"Results"}},"type":"object","required":["total","limit","offset","sort","results"],"title":"AgentQueryResponse"},"AgentStatementResponse":{"properties":{"wallet":{"type":"string","title":"Wallet"},"as_of":{"type":"string","format":"date-time","title":"As Of"},"tier":{"type":"string","title":"Tier"},"reputation_score":{"type":"number","title":"Reputation Score"},"founding_member":{"type":"boolean","title":"Founding Member"},"registered_at":{"type":"string","format":"date-time","title":"Registered At"},"position":{"$ref":"#/components/schemas/StatementPosition"},"stake_event_count":{"type":"integer","title":"Stake Event Count"},"slash_event_count":{"type":"integer","title":"Slash Event Count"},"first_staked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Staked At"},"ledger":{"items":{"$ref":"#/components/schemas/StatementLedgerEntry"},"type":"array","title":"Ledger"},"note":{"type":"string","title":"Note"}},"type":"object","required":["wallet","as_of","tier","reputation_score","founding_member","registered_at","position","stake_event_count","slash_event_count","first_staked_at","ledger","note"],"title":"AgentStatementResponse"},"AgentStatusResponse":{"properties":{"wallet":{"type":"string","title":"Wallet"},"tier":{"type":"string","title":"Tier"},"stake_amount":{"type":"number","title":"Stake Amount"},"unbonding_amount":{"type":"number","title":"Unbonding Amount"},"reputation_score":{"type":"number","title":"Reputation Score"},"slash_count":{"type":"integer","title":"Slash Count"},"founding_member":{"type":"boolean","title":"Founding Member"},"last_updated":{"type":"string","format":"date-time","title":"Last Updated"}},"type":"object","required":["wallet","tier","stake_amount","unbonding_amount","reputation_score","slash_count","founding_member","last_updated"],"title":"AgentStatusResponse"},"Erc8004Response":{"properties":{"wallet":{"type":"string","title":"Wallet"},"chain_id":{"type":"integer","title":"Chain Id"},"identity_registry":{"type":"string","title":"Identity Registry"},"reputation_registry":{"type":"string","title":"Reputation Registry"},"found":{"type":"boolean","title":"Found"},"agent_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Agent Id"},"global_agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Global Agent Id"},"onchain_reputation_summary":{"anyOf":[{"$ref":"#/components/schemas/Erc8004Summary"},{"type":"null"}]},"checked_at":{"type":"string","format":"date-time","title":"Checked At"},"note":{"type":"string","title":"Note"}},"type":"object","required":["wallet","chain_id","identity_registry","reputation_registry","found","agent_id","global_agent_id","onchain_reputation_summary","checked_at","note"],"title":"Erc8004Response"},"Erc8004Summary":{"properties":{"count":{"type":"integer","title":"Count"},"average_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Value"}},"type":"object","required":["count","average_value"],"title":"Erc8004Summary"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LeaderboardEntry":{"properties":{"wallet":{"type":"string","title":"Wallet"},"tier":{"type":"string","title":"Tier"},"stake_amount":{"type":"number","title":"Stake Amount"},"reputation_score":{"type":"number","title":"Reputation Score"},"slash_count":{"type":"integer","title":"Slash Count"},"founding_member":{"type":"boolean","title":"Founding Member"},"registered_at":{"type":"string","format":"date-time","title":"Registered At"}},"type":"object","required":["wallet","tier","stake_amount","reputation_score","slash_count","founding_member","registered_at"],"title":"LeaderboardEntry"},"NonceResponse":{"properties":{"wallet_address":{"type":"string","title":"Wallet Address"},"nonce":{"type":"string","title":"Nonce"},"message":{"type":"string","title":"Message"},"expires_in_seconds":{"type":"integer","title":"Expires In Seconds"}},"type":"object","required":["wallet_address","nonce","message","expires_in_seconds"],"title":"NonceResponse"},"RegisterRequest":{"properties":{"wallet_address":{"type":"string","title":"Wallet Address"},"nonce":{"type":"string","title":"Nonce"},"signature":{"type":"string","title":"Signature"}},"type":"object","required":["wallet_address","nonce","signature"],"title":"RegisterRequest"},"SlashRequest":{"properties":{"amount":{"type":"number","exclusiveMinimum":0.0,"title":"Amount"},"reason":{"type":"string","title":"Reason"},"triggered_by":{"type":"string","title":"Triggered By"},"evidence":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evidence"}},"type":"object","required":["amount","reason","triggered_by"],"title":"SlashRequest"},"StakeRequest":{"properties":{"nonce":{"type":"string","title":"Nonce"},"signature":{"type":"string","title":"Signature"},"tx_hash":{"type":"string","maxLength":66,"minLength":66,"title":"Tx Hash"},"amount":{"type":"number","exclusiveMinimum":0.0,"title":"Amount"}},"type":"object","required":["nonce","signature","tx_hash","amount"],"title":"StakeRequest"},"StatementLedgerEntry":{"properties":{"type":{"type":"string","title":"Type"},"amount":{"type":"number","title":"Amount"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"tx_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tx Hash"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"at":{"type":"string","format":"date-time","title":"At"}},"type":"object","required":["type","amount","at"],"title":"StatementLedgerEntry"},"StatementPosition":{"properties":{"active_stake":{"type":"number","title":"Active Stake"},"unbonding_stake":{"type":"number","title":"Unbonding Stake"},"total_withdrawn":{"type":"number","title":"Total Withdrawn"},"total_slashed":{"type":"number","title":"Total Slashed"},"lifetime_staked":{"type":"number","title":"Lifetime Staked"}},"type":"object","required":["active_stake","unbonding_stake","total_withdrawn","total_slashed","lifetime_staked"],"title":"StatementPosition"},"TierOut":{"properties":{"tier_name":{"type":"string","title":"Tier Name"},"min_stake_required":{"type":"number","title":"Min Stake Required"},"rate_limit_multiplier":{"type":"number","title":"Rate Limit Multiplier"},"fee_discount_pct":{"type":"number","title":"Fee Discount Pct"},"rank":{"type":"integer","title":"Rank"}},"type":"object","required":["tier_name","min_stake_required","rate_limit_multiplier","fee_discount_pct","rank"],"title":"TierOut"},"TransparencyResponse":{"properties":{"staking_wallet_address":{"type":"string","title":"Staking Wallet Address"},"chain_id":{"type":"integer","title":"Chain Id"},"usdc_contract_address":{"type":"string","title":"Usdc Contract Address"},"explorer_url":{"type":"string","title":"Explorer Url"},"custody_model":{"type":"string","title":"Custody Model"},"unbonding_cooldown_seconds":{"type":"integer","title":"Unbonding Cooldown Seconds"},"total_active_stake":{"type":"number","title":"Total Active Stake"},"total_agents":{"type":"integer","title":"Total Agents"},"total_slash_events":{"type":"integer","title":"Total Slash Events"},"founding_slots_total":{"type":"integer","title":"Founding Slots Total"},"founding_slots_claimed":{"type":"integer","title":"Founding Slots Claimed"},"erc8004_identity_registry":{"type":"string","title":"Erc8004 Identity Registry"},"erc8004_reputation_registry":{"type":"string","title":"Erc8004 Reputation Registry"},"self_erc8004_agent_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Self Erc8004 Agent Id"},"self_erc8004_global_agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Self Erc8004 Global Agent Id"}},"type":"object","required":["staking_wallet_address","chain_id","usdc_contract_address","explorer_url","custody_model","unbonding_cooldown_seconds","total_active_stake","total_agents","total_slash_events","founding_slots_total","founding_slots_claimed","erc8004_identity_registry","erc8004_reputation_registry","self_erc8004_agent_id","self_erc8004_global_agent_id"],"title":"TransparencyResponse"},"UnstakeRequest":{"properties":{"nonce":{"type":"string","title":"Nonce"},"signature":{"type":"string","title":"Signature"},"amount":{"type":"number","exclusiveMinimum":0.0,"title":"Amount"}},"type":"object","required":["nonce","signature","amount"],"title":"UnstakeRequest"},"UnstakeResponse":{"properties":{"wallet":{"type":"string","title":"Wallet"},"amount":{"type":"number","title":"Amount"},"status":{"type":"string","title":"Status","default":"unbonding"},"withdrawable_at":{"type":"string","format":"date-time","title":"Withdrawable At"},"current_tier":{"type":"string","title":"Current Tier"},"erc8004_feedback_tx_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Erc8004 Feedback Tx Hash"}},"type":"object","required":["wallet","amount","withdrawable_at","current_tier"],"title":"UnstakeResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WithdrawRequest":{"properties":{"nonce":{"type":"string","title":"Nonce"},"signature":{"type":"string","title":"Signature"}},"type":"object","required":["nonce","signature"],"title":"WithdrawRequest"},"WithdrawResponse":{"properties":{"wallet":{"type":"string","title":"Wallet"},"amount":{"type":"number","title":"Amount"},"tx_hash":{"type":"string","title":"Tx Hash"}},"type":"object","required":["wallet","amount","tx_hash"],"title":"WithdrawResponse"}}}}