{"openapi":"3.1.0","info":{"title":"Wicked Identity","description":"Reverse-CAPTCHA / Know-Your-Agent verification service: proves an HTTP caller is (or is not) an autonomous AI agent, and binds that to a specific, accountable wallet. See README for the challenge methodology and honest false-positive/negative limitations.","version":"0.1.0"},"servers":[{"url":"https://verify.wickedapi.com","description":"Production (Base mainnet x402)"}],"paths":{"/agents/{wallet}/nonce":{"get":{"tags":["onboarding"],"summary":"Get Nonce","description":"Issue a one-time, short-lived nonce to sign for wallet-signature auth.\nRequired before POST /agents/register, POST /verify/challenge, or\nPOST /verify/response -- fetch a fresh one for each, they're single-use.","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":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/register":{"post":{"tags":["onboarding"],"summary":"Register Agent","description":"Wallet-signature-authenticated. Creates a lightweight identity record\n-- no stake required (build.txt endpoint 1). Does not touch Wicked\nReputation's agents/stake data; that's cross-checked live over HTTP at\nverification time instead (see app/reputation_client.py).","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"}}}}}}},"/sandbox/register":{"post":{"tags":["onboarding"],"summary":"Sandbox Register","description":"No wallet, no signing, no body. Returns a sandbox `wallet` address and a\none-time `sandbox_token`. Pass both to POST /verify/challenge and\nPOST /verify/response as `wallet_address` and `sandbox_token` (leave out\nnonce/signature). The token is shown once and only its hash is stored.","operationId":"sandbox_register_sandbox_register_post","responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/keys/test":{"post":{"tags":["onboarding"],"summary":"Create Test Key","description":"Issue a test API key. Send it as the `x-api-key` header on\nGET /verify/status/{wallet}. Expires after a few days and is limited to a\nlow request rate; the key is shown once and only its hash is stored.","operationId":"create_test_key_keys_test_post","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TestKeyRequest"},{"type":"null"}],"title":"Payload"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/verify/challenge":{"post":{"tags":["verification"],"summary":"Issue Challenge","description":"Issue a new time-boxed liveness/agent-ness challenge for a registered\nwallet (build.txt endpoint 2). Wallet-signature-authenticated.","operationId":"issue_challenge_verify_challenge_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChallengeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/verify/response":{"post":{"tags":["verification"],"summary":"Submit Response","description":"Score a challenge response for real -- never a default-pass or cached\nassumption (build.txt CRITICAL CONSTRAINT). On pass, issues a signed\nshort-lived assertion (build.txt endpoint 3).","operationId":"submit_response_verify_response_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResponseRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/verify/status/{wallet}":{"get":{"tags":["verification"],"summary":"Verify Status","description":"PUBLIC. Does this wallet currently hold a valid, unexpired assertion?\nFree for x-api-key holders (rate-limited); a real 402 challenge for\nkeyless callers, matching WickedAPI's exact x402 model (build.txt\nendpoint 4).","operationId":"verify_status_verify_status__wallet__get","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string","title":"Wallet"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/.well-known/jwks.json":{"get":{"tags":["discovery"],"summary":"Get Jwks","description":"Standard JWKS (RFC 7517): the public RS256 key(s) used to sign\nassertion tokens, for independent local verification with any standard\nJWT library -- no callback to this service required.","operationId":"get_jwks__well_known_jwks_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/jwks-sandbox.json":{"get":{"tags":["discovery"],"summary":"Get Sandbox Jwks","description":"JWKS for SANDBOX assertions only (issuer `wicked-identity-sandbox`).\nDeliberately a separate key set from /.well-known/jwks.json: a relying\nparty that verifies against the production JWKS can never accept a\nsandbox token, because it is not signed by any key published there.","operationId":"get_sandbox_jwks__well_known_jwks_sandbox_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/admin/agents/{wallet}/revoke":{"post":{"summary":"Revoke Agent","description":"Admin-API-key only (not wallet-signature -- build.txt endpoint 6,\nmatching Wicked Reputation's slash-endpoint auth split). Revokes all\nlive assertions for a wallet and logs the reason.","operationId":"revoke_agent_admin_agents__wallet__revoke_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/RevokeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"tags":["discovery"],"summary":"Health","description":"Liveness check. Returns {\"status\": \"ok\"} when the service is up.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/status":{"get":{"tags":["discovery"],"summary":"V1 Status","description":"Machine-readable catalog of every endpoint this service exposes.","operationId":"v1_status_v1_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"ChallengeRequest":{"properties":{"wallet_address":{"type":"string","title":"Wallet Address"},"nonce":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nonce"},"signature":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signature"},"sandbox_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sandbox Token"}},"type":"object","required":["wallet_address"],"title":"ChallengeRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"},"RevokeRequest":{"properties":{"reason":{"type":"string","title":"Reason"}},"type":"object","required":["reason"],"title":"RevokeRequest"},"TestKeyRequest":{"properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"}},"type":"object","title":"TestKeyRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VerifyResponseRequest":{"properties":{"wallet_address":{"type":"string","title":"Wallet Address"},"nonce":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nonce"},"signature":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signature"},"sandbox_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sandbox Token"},"challenge_id":{"type":"string","title":"Challenge Id"},"response_text":{"type":"string","title":"Response Text"}},"type":"object","required":["wallet_address","challenge_id","response_text"],"title":"VerifyResponseRequest"}}},"tags":[{"name":"onboarding","description":"Wallet-signature auth: get a nonce, register."},{"name":"verification","description":"Challenge/response verification and status lookup."},{"name":"discovery","description":"JWKS, service catalog, health."}]}