# Wicked Identity -- complete agent integration guide Base URL: https://verify.wickedapi.com OpenAPI: https://verify.wickedapi.com/openapi.json Short version of this file: https://verify.wickedapi.com/llms.txt Wicked Identity proves that a caller completed a time-boxed, automation-favoring challenge, and binds that proof to a wallet. On success you get a signed JWT ("assertion") that anyone can verify offline. It is a friction/signal layer, NOT a guarantee of non-humanity: a human relaying the challenge to their own LLM can pass it. Treat a pass as "completed a time-boxed automation-favoring challenge". ## Two ways in A) No wallet / can't sign (chat agents, MCP-only agents, quick tests): SANDBOX identity. 1. POST /sandbox/register -> {wallet, sandbox_token} (no body, no signing) 2. POST /verify/challenge body {wallet_address, sandbox_token} -> clock starts 3. POST /verify/response body {wallet_address, sandbox_token, challenge_id, response_text} Two calls on the clock, no nonces, no signatures. Sandbox is for trying the service: its assertion is signed with a SEPARATE key and issuer (wicked-identity-sandbox, verify at /.well-known/jwks-sandbox.json), carries "sandbox": true, and GET /verify/status never reports a sandbox wallet as verified (it returns sandbox: true, sandbox_verified: true|false instead). Limit: 10 sandbox registrations per IP per hour. B) Real wallet (accountable identity): wallet signatures, below. This is the one relying parties should trust. ## The flow at a glance (real wallet) 1. GET /agents/{wallet}/nonce -> sign the returned `message` (once, to register) 2. POST /agents/register -> wallet is now known 3. GET /agents/{wallet}/nonce -> sign it (auth for the challenge request) 4. GET /agents/{wallet}/nonce -> sign it (PRE-FETCH: auth for the response, see timing) 5. POST /verify/challenge -> timer starts NOW (default 30s) 6. solve the task 7. POST /verify/response -> result + assertion_token on pass Registration (steps 1-2) is one-time per wallet. Re-verifying later is steps 3-7. ## TIMING -- read this, it is the #1 way to fail The challenge clock starts when POST /verify/challenge returns, not when you start working. Every nonce is single-use and every authenticated call needs a fresh one, so: - Fetch AND sign the nonce for /verify/response BEFORE you call /verify/challenge. Nonces stay valid for 300 seconds, so this is safe. - Do not fetch a nonce, sign, or make any other network call while the clock runs. - Do not plan your answer in a slow multi-step loop: generate the answer in one pass and submit immediately. A correct answer that arrives just after the deadline (within a short grace window) scores "inconclusive", not "fail". A wrong answer or a very late one is "fail". You can simply request a new challenge and try again. ## Free test API key (no signup, no payment) POST /keys/test (optional body {"label": "my agent"}) -> {"data": {"api_key": "wk_test_...", "expires_at": "...", "rate_limit_per_min": 20}} Send it as header `x-api-key` on GET /verify/status/{wallet} to skip the x402 payment. Test keys expire after 7 days and allow 20 requests/minute. The key is shown once. Limit: 5 keys per IP per day. ## Auth: wallet signatures (EIP-191 personal_sign) 1. GET /agents/{wallet}/nonce returns: {"data": {"wallet_address": "0x..", "nonce": "", "message": "", "expires_in_seconds": 300}} 2. Sign the `message` string EXACTLY as returned with personal_sign (EIP-191). Do not modify, re-encode or re-case it. The wallet address is lowercased in the message. 3. Send wallet_address, nonce and signature (0x-prefixed hex) in the request body. The signing key must belong to the wallet you are registering/verifying. ## Complete worked example (Python: pip install eth-account requests) import requests from eth_account import Account from eth_account.messages import encode_defunct BASE = "https://verify.wickedapi.com" acct = Account.from_key(PRIVATE_KEY) # your agent's wallet key wallet = acct.address def signed_auth(): """Fetch a fresh nonce and sign it. Single-use: call once per authenticated request.""" n = requests.get(f"{BASE}/agents/{wallet}/nonce").json()["data"] sig = Account.sign_message(encode_defunct(text=n["message"]), private_key=acct.key).signature.hex() if not sig.startswith("0x"): sig = "0x" + sig return {"wallet_address": wallet, "nonce": n["nonce"], "signature": sig} # --- one-time registration (409 "already registered" is fine, ignore it) --- requests.post(f"{BASE}/agents/register", json=signed_auth()) # --- verification --- challenge_auth = signed_auth() response_auth = signed_auth() # PRE-FETCH before the clock starts ch = requests.post(f"{BASE}/verify/challenge", json=challenge_auth).json()["data"] # ch["instructions"] is the task; ch["time_budget_seconds"] is your budget. answer = solve(ch["instructions"]) # <- your LLM call: raw text only, single pass res = requests.post(f"{BASE}/verify/response", json={ **response_auth, "challenge_id": ch["challenge_id"], "response_text": answer, }).json()["data"] print(res["result"], res["reason"]) # pass | fail | inconclusive token = res["assertion_token"] # JWT on pass, else null ## The challenge (what `solve` must do) `instructions` is plain English, e.g.: write EXACTLY N words about a topic; only lowercase a-z words separated by single spaces (no digits/punctuation/capitals); and the sum of the alphabet positions of each word's FIRST letter (a=1 ... z=26) must equal exactly T. Respond with the raw text only, nothing else. Tips: the answer must satisfy BOTH constraints at once. Pick words so first-letter positions add to T, count them, output only the words. No preamble, no quotes, no trailing newline games. Each challenge is different -- never reuse an old answer. ## Result values result meaning assertion_token pass both constraints met inside the window JWT issued inconclusive near-miss, or correct but just late null (request a new challenge) fail wrong, malformed, or far too late null `confidence_score` (0-1) is a soft signal; `reputation_bonus_applied` is true when the wallet also holds an active stake on Wicked Reputation (https://stake.wickedapi.com). ## Using the assertion (relying parties) The token is a standard RS256 JWT. Claims: sub (wallet, lowercase), iss ("wicked-identity"), iat, exp (default 15 minutes). Verify it OFFLINE against the public JWKS: import jwt # pip install pyjwt[crypto] jwks = jwt.PyJWKClient("https://verify.wickedapi.com/.well-known/jwks.json") key = jwks.get_signing_key_from_jwt(token).key claims = jwt.decode(token, key, algorithms=["RS256"], issuer="wicked-identity") assert claims["sub"] == expected_wallet.lower() Caveat: offline verification cannot see revocation. If you must honor revocations before expiry, call GET /verify/status/{wallet} instead (or as well). ## Checking status: GET /verify/status/{wallet} Public and read-only. Two ways in: - free: send header `x-api-key: ` (rate limited per key). Get a test key instantly with POST /keys/test (see above); partner keys are separate and higher-limit. - paid: no key -> HTTP 402 with x402 payment terms, $0.001 USDC per call on Base mainnet (eip155:8453). An x402-capable client pays and retries automatically. The 402 carries the machine-readable terms in the `PAYMENT-REQUIRED` response header (base64-encoded JSON, x402 v2); the JSON body repeats the price/network in plain English. A malformed wallet address returns HTTP 400 once past the gate (valid key, or payment verified); an unpaid caller always gets the 402 challenge first, and a bad address is rejected before settlement, so it is never charged. Response: {"data": {"wallet", "verified": bool, "expires_at", "confidence_score", "reputation_bonus_applied"}, "meta": {...}} ## Errors Every error is JSON: {"error": "", "source": ""}. Validation errors (422) additionally include "details": [{"field", "problem"}]. 400 malformed wallet address 401 unknown/used/expired nonce, bad signature, missing api key with x402 unavailable 402 payment required (GET /verify/status only) 404 wallet not registered (register first) or unknown challenge_id 409 already registered, or challenge already completed/expired 422 request body missing or malformed fields 429 rate limit exceeded (x-api-key path); honor the Retry-After header "Unknown or already-used nonce" almost always means a nonce was reused. Fetch a new one. ## MCP The same flow is exposed as MCP tools (identity_get_nonce, identity_register, identity_get_challenge, identity_submit_response, identity_status, identity_jwks) in the open-source wicked-mcp server: https://github.com/choaticpixels/wicked-mcp ## Discovery Landing page https://verify.wickedapi.com/ Swagger UI https://verify.wickedapi.com/docs OpenAPI https://verify.wickedapi.com/openapi.json Catalog https://verify.wickedapi.com/v1/status JWKS https://verify.wickedapi.com/.well-known/jwks.json JWKS (sandbox) https://verify.wickedapi.com/.well-known/jwks-sandbox.json x402 Bazaar GET /verify/status/:wallet declares Bazaar discovery metadata in its 402 response