{"openapi":"3.1.0","info":{"title":"8004scan Backend API","description":"Backend service for ERC-8004 agent registry.\n\n## 🔐 Authentication\n\nUse the **Authorize** button above to set your JWT token for authenticated endpoints.\n\n**Two authentication methods supported:**\n1. **X-Access-Token** header (recommended)\n2. **Authorization: Bearer** header (standard JWT auth)\n\n**To get a token:**\n1. Visit [/test/login](/test/login) to login with MetaMask\n2. Copy the Access Token\n3. Click **Authorize** button → paste token → **Authorize**\n\nOr use the API directly:\n1. `POST /api/v1/auth/nonce` - Get a nonce\n2. Sign the message with your wallet\n3. `POST /api/v1/auth/login` - Get JWT tokens\n","version":"0.4.370"},"paths":{"/health":{"get":{"summary":"Health Check","description":"Liveness probe endpoint\n\nUsed by K8s liveness probe to verify the application process is running.\nDoes NOT check external dependencies (database, redis, etc.)\nto avoid unnecessary restarts when dependencies are temporarily unavailable.\n\nReturns:\n    - status: always \"healthy\" if the app is running\n    - version: application version\n    - environment: deployment environment (development/staging/production)","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ready":{"get":{"summary":"Readiness Check","description":"Readiness probe endpoint\n\nUsed by K8s readiness probe to verify the application is ready to receive traffic.\nChecks all critical dependencies (database, redis, etc.)\n\nReturns:\n    - status: \"healthy\", \"degraded\", or \"unhealthy\"\n    - version: application version\n    - environment: deployment environment\n    - components: list of dependency health statuses\n\nHTTP Status:\n    - 200: healthy or degraded (can serve traffic)\n    - 503: unhealthy (should not receive traffic)","operationId":"readiness_check_ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/test/login":{"get":{"summary":"Serve Login Page","description":"Serve MetaMask login test page","operationId":"serve_login_page_test_login_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/auth/nonce":{"post":{"tags":["auth"],"summary":"Get Nonce","description":"Get a nonce for wallet signature authentication.\n\nThe client should:\n1. Call this endpoint with their wallet address\n2. Sign the returned message with their wallet\n3. Call /auth/login with the wallet address, signature, and nonce\n\nThe nonce expires after 10 minutes.","operationId":"get_nonce_api_v1_auth_nonce_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NonceRequest"}}},"required":true},"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"}}}}}}},"/api/v1/auth/login":{"post":{"tags":["auth"],"summary":"Login With Wallet","description":"Authenticate user with wallet signature.\n\nSupports:\n- EOA wallets (EIP-191 personal_sign)\n- Smart contract wallets (ERC-1271)\n- Coinbase Embedded Wallet (ERC-6492)\n\nThis endpoint:\n1. Verifies the wallet signature (EOA/ERC-1271/ERC-6492)\n2. Gets or creates a user account for this wallet\n3. Creates a Supabase Auth session (optional - for JWT generation)\n4. Returns a JWT access token\n\nNote: For ERC-6492 signatures, chain_id is required in the request.","operationId":"login_with_wallet_api_v1_auth_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletLoginRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/logout":{"post":{"tags":["auth"],"summary":"Logout","description":"Logout current user.\n\nThis endpoint invalidates the current session.\nIn a JWT-based system, the client should delete the token from storage.","operationId":"logout_api_v1_auth_logout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogoutResponse"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/auth/refresh":{"post":{"tags":["auth"],"summary":"Refresh Access Token","description":"Refresh access token using refresh token.\n\nThis endpoint allows clients to obtain a new access token without re-authenticating.\nThe refresh token must be valid and not expired.","operationId":"refresh_access_token_api_v1_auth_refresh_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/me":{"get":{"tags":["auth"],"summary":"Get Current User Profile","description":"Get current authenticated user profile.\n\nThis endpoint requires authentication (Bearer token in Authorization header).","operationId":"get_current_user_profile_api_v1_auth_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentUserResponse"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]},"put":{"tags":["auth"],"summary":"Update Current User Profile","description":"Update current authenticated user profile.\n\nThis endpoint requires authentication (Bearer token in Authorization header).","operationId":"update_current_user_profile_api_v1_auth_me_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentUserUpdate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentUserResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/chains":{"get":{"tags":["chains"],"summary":"List Chains","description":"List all configured chains with their testnet/mainnet status.\n\nReturns chain information to help frontend filter resources by network type.\n\n**Response includes:**\n- `chains`: List of all chains with their metadata\n- `testnet_chain_ids`: List of testnet chain IDs for easy filtering\n- `mainnet_chain_ids`: List of mainnet chain IDs for easy filtering","operationId":"list_chains_api_v1_chains_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response List Chains Api V1 Chains Get"}}}}}}},"/api/v1/chains/{chain_id}":{"get":{"tags":["chains"],"summary":"Get Chain","description":"Get information for a specific chain by chain_id.\n\nReturns chain metadata including testnet/mainnet status.","operationId":"get_chain_api_v1_chains__chain_id__get","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Chain Api V1 Chains  Chain Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/donations/config":{"get":{"tags":["donations"],"summary":"Get Donation Config","description":"Return backend-owned donation payment details for the frontend.","operationId":"get_donation_config_api_v1_donations_config_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/DonationConfigResponse"},"type":"array","title":"Response Get Donation Config Api V1 Donations Config Get"}}}}}}},"/api/v1/donations/pay":{"post":{"tags":["donations"],"summary":"Pay Donation","description":"Process an x402 donation and return the backend receipt.","operationId":"pay_donation_api_v1_donations_pay_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DonationPayRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/donations/leaderboard":{"get":{"tags":["donations"],"summary":"Get Donation Leaderboard","description":"Return top verified donors without exposing full wallet addresses.","operationId":"get_donation_leaderboard_api_v1_donations_leaderboard_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DonationLeaderboardResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/donations/recent":{"get":{"tags":["donations"],"summary":"Get Recent Donations","description":"Return recent verified donations without exposing full wallet addresses.","operationId":"get_recent_donations_api_v1_donations_recent_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecentDonationsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/donations/status/{client_payment_id}":{"get":{"tags":["donations"],"summary":"Get Donation Status","description":"Return donation status by optional frontend-generated client payment ID.","operationId":"get_donation_status_api_v1_donations_status__client_payment_id__get","parameters":[{"name":"client_payment_id","in":"path","required":true,"schema":{"type":"string","title":"Client Payment Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DonationStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/register":{"post":{"tags":["users"],"summary":"Register User","description":"Register a new user with a wallet address.\nThe wallet will be set as the primary wallet.","operationId":"register_user_api_v1_users_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{identifier}/card":{"get":{"tags":["users"],"summary":"Get User Card","description":"Get lightweight user info for hover cards.\n\nThis endpoint is optimized for fast retrieval (~50ms target) with minimal data.\nResults are cached for 60 seconds.\n\nThe identifier can be:\n- UUID: e.g., \"550e8400-e29b-41d4-a716-446655440000\"\n- Wallet address: e.g., \"0x1234567890abcdef1234567890abcdef12345678\"\n\nReturns basic user info suitable for displaying in a hover card popup,\nincluding:\n- Address and ENS name\n- Username and avatar\n- Verification/certification status\n- Basic stats (agents, feedbacks)\n- Follow status (if authenticated)\n\nNote: For addresses without a registered user, returns minimal info\nwith just the address and ENS name (if available).","operationId":"get_user_card_api_v1_users__identifier__card_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCardResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{identifier}":{"get":{"tags":["users"],"summary":"Get User","description":"Get user by ID or wallet address.\n\nThe identifier can be:\n- UUID: e.g., \"550e8400-e29b-41d4-a716-446655440000\"\n- Wallet address: e.g., \"0x1234567890abcdef1234567890abcdef12345678\"\n\nThe endpoint auto-detects the format and queries accordingly.\n\nNote: Admin status is not exposed in this endpoint. Use /auth/me for your own\nadmin status, or /admin/users for admin user management (requires SUPER admin).","operationId":"get_user_api_v1_users__identifier__get","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{user_id}":{"patch":{"tags":["users"],"summary":"Update User","description":"Update user profile","operationId":"update_user_api_v1_users__user_id__patch","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{user_id}/wallets":{"get":{"tags":["users"],"summary":"Get User Wallets","description":"Get all wallets linked to a user.","operationId":"get_user_wallets_api_v1_users__user_id__wallets_get","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/app__schemas__user__WalletResponse"},"title":"Response Get User Wallets Api V1 Users  User Id  Wallets Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["users"],"summary":"Add Wallet","description":"Add a new wallet to existing user","operationId":"add_wallet_api_v1_users__user_id__wallets_post","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{user_id}/wallets/merge":{"post":{"tags":["users"],"summary":"Request Wallet Merge","description":"Step 1: Request to merge a wallet into user account.\n\nThis endpoint returns a challenge message that must be signed by the wallet\nto prove ownership. The wallet being merged may belong to another user account,\nin which case all assets will be transferred.\n\nFlow:\n1. Call this endpoint with the wallet address to merge\n2. Sign the returned message with the wallet\n3. Call /users/{user_id}/wallets/merge/confirm with the signature","operationId":"request_wallet_merge_api_v1_users__user_id__wallets_merge_post","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletMergeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletMergeChallenge"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{user_id}/wallets/merge/confirm":{"post":{"tags":["users"],"summary":"Confirm Wallet Merge","description":"Step 2: Confirm wallet merge with signature.\n\nAfter signing the challenge message from step 1, submit the signature here\nto complete the merge operation.\n\nIf the wallet belongs to another user:\n- All agents owned by that user will be transferred\n- All feedbacks will be transferred\n- All validations will be transferred\n- All stars/watches will be transferred\n- The other user account will be deleted","operationId":"confirm_wallet_merge_api_v1_users__user_id__wallets_merge_confirm_post","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletMergeConfirm"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletMergeResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/me/donations":{"get":{"tags":["users"],"summary":"List My Donations","description":"List donations associated with the current user's linked wallets.","operationId":"list_my_donations_api_v1_users_me_donations_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"verified","title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserDonationListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/me/donations/rank":{"get":{"tags":["users"],"summary":"Get My Donation Rank","description":"Return the current user's donation rank and exact cumulative amount.","operationId":"get_my_donation_rank_api_v1_users_me_donations_rank_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserDonationRankResponse"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/users/me/delete":{"post":{"tags":["users"],"summary":"Request Account Deletion","description":"Step 1: Request account deletion challenge.\n\nReturns a challenge message that must be signed by the user's primary wallet\nto confirm the deletion. This provides cryptographic proof of intent.\n\nFlow:\n1. Call this endpoint to get a challenge message\n2. Sign the message with your primary wallet\n3. Call POST /users/me/delete/confirm with the signature","operationId":"request_account_deletion_api_v1_users_me_delete_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserDeleteChallenge"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/users/me/delete/confirm":{"post":{"tags":["users"],"summary":"Confirm Account Deletion","description":"Step 2: Confirm account deletion with wallet signature.\n\n⚠️ WARNING: This action is IRREVERSIBLE!\n\nAfter signing the challenge message from step 1, submit the signature here\nto complete the account deletion.\n\nThis operation:\n1. Deletes all user off-chain data (profile, stars, watches, chats, memories,\n   API keys, subscriptions, certifications, inbox messages, analytics)\n2. Removes webhook registrations\n3. Sets user_id to NULL on feedbacks/validations/agents (preserving on-chain data)\n4. Creates new empty users for each wallet address (restoring to pure on-chain state)\n\nAfter deletion:\n- The wallet addresses can sign in again but will have fresh empty accounts\n- On-chain data (agents, feedbacks, validations) remains associated with wallet addresses\n- All personalization and preferences are permanently removed","operationId":"confirm_account_deletion_api_v1_users_me_delete_confirm_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserDeleteConfirm"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/users/me/notification-settings":{"get":{"tags":["users"],"summary":"Get Notification Settings","description":"Get notification settings for the current user.\n\nReturns the user's notification preferences including:\n- Inbox notifications (which events generate inbox messages)\n- Webhook notifications (which events trigger webhooks)","operationId":"get_notification_settings_api_v1_users_me_notification_settings_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationSettingsResponse"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]},"put":{"tags":["users"],"summary":"Update Notification Settings","description":"Update notification settings for the current user.\n\nSupports partial updates - only provide the channels/events you want to change.","operationId":"update_notification_settings_api_v1_users_me_notification_settings_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationSettingsUpdate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationSettingsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/users/{identifier}/follow":{"post":{"tags":["users"],"summary":"Follow User","description":"Follow a user.\n\nThe identifier can be:\n- UUID: e.g., \"550e8400-e29b-41d4-a716-446655440000\"\n- Wallet address: e.g., \"0x1234567890abcdef1234567890abcdef12345678\"\n\nReturns:\n- success: True if followed, False if already following or self-follow\n- message: Description of the result\n- follower_count: Updated follower count of the target user\n- following_count: Updated following count of the current user","operationId":"follow_user_api_v1_users__identifier__follow_post","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["users"],"summary":"Unfollow User","description":"Unfollow a user.\n\nThe identifier can be:\n- UUID: e.g., \"550e8400-e29b-41d4-a716-446655440000\"\n- Wallet address: e.g., \"0x1234567890abcdef1234567890abcdef12345678\"\n\nReturns:\n- success: True if unfollowed, False if not following\n- message: Description of the result\n- follower_count: Updated follower count of the target user\n- following_count: Updated following count of the current user","operationId":"unfollow_user_api_v1_users__identifier__follow_delete","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{identifier}/follow-status":{"get":{"tags":["users"],"summary":"Get Follow Status","description":"Get follow status between current user and target user.\n\nThe identifier can be:\n- UUID: e.g., \"550e8400-e29b-41d4-a716-446655440000\"\n- Wallet address: e.g., \"0x1234567890abcdef1234567890abcdef12345678\"\n\nReturns:\n- is_following: Whether current user follows target user\n- is_followed_by: Whether target user follows current user","operationId":"get_follow_status_api_v1_users__identifier__follow_status_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{identifier}/followers":{"get":{"tags":["users"],"summary":"Get Followers","description":"Get list of followers for a user.\n\nThe identifier can be:\n- UUID: e.g., \"550e8400-e29b-41d4-a716-446655440000\"\n- Wallet address: e.g., \"0x1234567890abcdef1234567890abcdef12345678\"\n\nReturns paginated list of followers with their basic info.","operationId":"get_followers_api_v1_users__identifier__followers_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"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/FollowerListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{identifier}/following":{"get":{"tags":["users"],"summary":"Get Following","description":"Get list of users that a user is following.\n\nThe identifier can be:\n- UUID: e.g., \"550e8400-e29b-41d4-a716-446655440000\"\n- Wallet address: e.g., \"0x1234567890abcdef1234567890abcdef12345678\"\n\nReturns paginated list of followed users with their basic info.","operationId":"get_following_api_v1_users__identifier__following_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"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/FollowerListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{identifier}/stats":{"get":{"tags":["user-stats"],"summary":"Get User Stats","description":"Get comprehensive user statistics\n\nThe identifier can be either:\n- UUID: Returns stats for a specific user account\n- Ethereum address (0x...): Returns stats for all activity from that address\n\nReturns:\n- Feedback statistics (total given, active, revoked, average score)\n- Validation statistics (requested, responded)\n- Agent statistics (owned, starred)\n- User flags (verified, official validator)\n- Activity timestamps (last feedback, last validation)","operationId":"get_user_stats_api_v1_users__identifier__stats_get","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","description":"User identifier: either a UUID or Ethereum address (0x...)","examples":["0x1234567890abcdef1234567890abcdef12345678","550e8400-e29b-41d4-a716-446655440000"],"title":"Identifier"},"description":"User identifier: either a UUID or Ethereum address (0x...)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserStatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{identifier}/feedbacks":{"get":{"tags":["user-stats"],"summary":"Get User Feedbacks","description":"Get all feedbacks submitted by a user or address\n\nParameters:\n- identifier: UUID or Ethereum address (0x...)\n- limit: Number of results to return (1-100, default 20)\n- offset: Offset for pagination (default 0)\n- include_revoked: Include revoked feedbacks (default false)\n\nReturns paginated list of feedbacks with:\n- Feedback ID, agent ID\n- Score and comment\n- Revoked status\n- Submission timestamp","operationId":"get_user_feedbacks_api_v1_users__identifier__feedbacks_get","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","description":"User identifier: either a UUID or Ethereum address (0x...)","examples":["0x1234567890abcdef1234567890abcdef12345678","550e8400-e29b-41d4-a716-446655440000"],"title":"Identifier"},"description":"User identifier: either a UUID or Ethereum address (0x...)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"include_revoked","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Revoked"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserFeedbacksListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{identifier}/validations/requested":{"get":{"tags":["user-stats"],"summary":"Get User Validations Requested","description":"Get all validations requested by a user or address\n\nParameters:\n- identifier: UUID or Ethereum address (0x...)\n- limit: Number of results to return (1-100, default 20)\n- offset: Offset for pagination (default 0)\n\nReturns paginated list of validation requests with:\n- Validation ID, agent ID\n- Status and vote\n- Comment\n- Timestamps","operationId":"get_user_validations_requested_api_v1_users__identifier__validations_requested_get","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","description":"User identifier: either a UUID or Ethereum address (0x...)","examples":["0x1234567890abcdef1234567890abcdef12345678","550e8400-e29b-41d4-a716-446655440000"],"title":"Identifier"},"description":"User identifier: either a UUID or Ethereum address (0x...)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserValidationsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{identifier}/validations/responded":{"get":{"tags":["user-stats"],"summary":"Get User Validations Responded","description":"Get all validations responded to by a user or address (as validator)\n\nParameters:\n- identifier: UUID or Ethereum address (0x...)\n- limit: Number of results to return (1-100, default 20)\n- offset: Offset for pagination (default 0)\n\nReturns paginated list of validation responses with:\n- Validation ID, agent ID\n- Status and vote\n- Comment\n- Timestamps","operationId":"get_user_validations_responded_api_v1_users__identifier__validations_responded_get","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","description":"User identifier: either a UUID or Ethereum address (0x...)","examples":["0x1234567890abcdef1234567890abcdef12345678","550e8400-e29b-41d4-a716-446655440000"],"title":"Identifier"},"description":"User identifier: either a UUID or Ethereum address (0x...)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserValidationsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/{identifier}/activity":{"get":{"tags":["user-stats"],"summary":"Get User Activity","description":"Get user or address activity timeline (feedbacks + validations combined)\n\nParameters:\n- identifier: UUID or Ethereum address (0x...)\n- limit: Number of recent activities to return (1-100, default 50)\n\nReturns combined activity timeline sorted by timestamp (most recent first):\n- Activity type (feedback, validation_requested, validation_responded)\n- Activity ID, agent ID\n- Type-specific fields (score, status, vote, etc.)\n- Timestamp","operationId":"get_user_activity_api_v1_users__identifier__activity_get","parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","description":"User identifier: either a UUID or Ethereum address (0x...)","examples":["0x1234567890abcdef1234567890abcdef12345678","550e8400-e29b-41d4-a716-446655440000"],"title":"Identifier"},"description":"User identifier: either a UUID or Ethereum address (0x...)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserActivityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/api-keys":{"post":{"tags":["api-keys"],"summary":"Create Api Key","description":"Create a new API key\n\n**Important**: The API key is only shown once. Save it securely!\n\n**Rate Limits**:\n- Free users: max 2 API keys\n- Basic tier: max 5 API keys\n- Pro tier: max 10 API keys\n- Enterprise: unlimited\n\n**Scopes**: (for future use)\n- `read:agents` - Read agent data\n- `write:agents` - Create/update agents\n- `read:validations` - Read validation data\n- `write:validations` - Create validation requests","operationId":"create_api_key_api_v1_api_keys_post","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["api-keys"],"summary":"List Api Keys","description":"List all API keys for the current user\n\n**Query Parameters**:\n- `include_inactive`: Include revoked/expired keys (default: false)","operationId":"list_api_keys_api_v1_api_keys_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"include_inactive","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Inactive"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/APIKeyResponse"},"title":"Response List Api Keys Api V1 Api Keys Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/api-keys/{key_id}":{"delete":{"tags":["api-keys"],"summary":"Revoke Api Key","description":"Revoke (delete) an API key\n\n**Note**: Revoked keys cannot be recovered. Create a new key if needed.","operationId":"revoke_api_key_api_v1_api_keys__key_id__delete","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Key Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["api-keys"],"summary":"Get Api Key","description":"Get details of a specific API key\n\n**Note**: The actual API key value is never returned. Only metadata.","operationId":"get_api_key_api_v1_api_keys__key_id__get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/api-keys/{key_id}/reveal":{"post":{"tags":["api-keys"],"summary":"Reveal Api Key","description":"Reveal the full API key value.\n\n**Security Notes**:\n- This endpoint only works for keys created after the reveal feature was added\n- Old keys cannot be revealed and will return `key: null`\n- The key is returned in the response body - ensure you're on a secure connection\n\n**Returns**:\n- `key`: The full API key string, or `null` if not available\n- `can_reveal`: Whether the key can be revealed\n\n**Rate Limiting**:\nThis endpoint is rate-limited to prevent abuse.","operationId":"reveal_api_key_api_v1_api_keys__key_id__reveal_post","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/api-keys/{key_id}/usage":{"get":{"tags":["api-keys"],"summary":"Get Api Key Usage","description":"Get usage statistics for an API key\n\n**Query Parameters**:\n- `days`: Number of days to include in breakdown (default: 7, max: 30)\n\n**Returns**:\n- Total requests\n- Daily breakdown\n- Current rate limits\n- Top endpoints","operationId":"get_api_key_usage_api_v1_api_keys__key_id__usage_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Key Id"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","default":7,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyUsageStats"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/users/me/email":{"post":{"tags":["email-verification"],"summary":"Update email address","description":"Update user's email address and send verification email.\n\nSteps:\n1. User provides new email\n2. System saves email to profile (unverified)\n3. System generates 6-digit verification code\n4. System sends code to new email\n5. User must verify with code to complete\n\nReturns:\n    Success message with instructions","operationId":"update_email_api_v1_users_me_email_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailUpdateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Update Email Api V1 Users Me Email Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/users/me/email/verify":{"post":{"tags":["email-verification"],"summary":"Verify email with code","description":"Verify email address with verification code.\n\nArgs:\n    verification_code: 6-digit code received via email\n\nReturns:\n    Success status and verification timestamp","operationId":"verify_email_api_v1_users_me_email_verify_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailVerificationRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailVerificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/users/me/email/resend":{"post":{"tags":["email-verification"],"summary":"Resend verification email","description":"Resend verification email with new code.\n\nReturns:\n    Success message","operationId":"resend_verification_email_api_v1_users_me_email_resend_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Resend Verification Email Api V1 Users Me Email Resend Post"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/users/me/email/status":{"get":{"tags":["email-verification"],"summary":"Get email verification status","description":"Get current email verification status.\n\nReturns:\n    Email and verification status","operationId":"get_email_status_api_v1_users_me_email_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Email Status Api V1 Users Me Email Status Get"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/users/me/certifications/validator/apply":{"post":{"tags":["user-certifications"],"summary":"[DEPRECATED] Apply for validator certification","description":"**DEPRECATED**: Validator certification is not supported by the ERC-8004 spec.\nThis endpoint will be removed in a future version.\n\nUser applies to become a validator.","operationId":"apply_for_validator_certification_api_v1_users_me_certifications_validator_apply_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorCertificationCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorCertificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"deprecated":true,"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/users/me/certifications/validator":{"get":{"tags":["user-certifications"],"summary":"[DEPRECATED] Get your validator certification status","description":"**DEPRECATED**: Validator certification is not supported by the ERC-8004 spec.\nThis endpoint will be removed in a future version.","operationId":"get_validator_certification_api_v1_users_me_certifications_validator_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ValidatorCertificationResponse"},{"type":"null"}],"title":"Response Get Validator Certification Api V1 Users Me Certifications Validator Get"}}}}},"deprecated":true,"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/users/me/certifications/publisher/apply":{"post":{"tags":["user-certifications"],"summary":"Apply for publisher certification","description":"Apply to become a certified Agent publisher.\n\nPublishers are developers/organizations that create and publish AI agents.\nThis creates a certification request with status 'pending'.\n\n**IMPORTANT**: After submitting, you MUST contact the 8004scan team via\nemail (team@8004scan.io) or Telegram to provide additional materials\nproving your project ownership. Applications will not be approved\nwithout verified communication.\n\nRequired fields:\n- reason: Why you want to publish agents (10-1000 chars)\n- organization_name: Your organization/project name\n- project_url: Project GitHub repo or official website\n- At least one of: organization_email or contact_telegram\n\nReturns:\n    PublisherCertificationResponse with status='pending'","operationId":"apply_for_publisher_certification_api_v1_users_me_certifications_publisher_apply_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherCertificationCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherCertificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/users/me/certifications/publisher":{"get":{"tags":["user-certifications"],"summary":"Get your publisher certification status","description":"Get your current publisher certification status.\n\nReturns:\n    PublisherCertificationResponse or None if no certification exists","operationId":"get_publisher_certification_api_v1_users_me_certifications_publisher_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PublisherCertificationResponse"},{"type":"null"}],"title":"Response Get Publisher Certification Api V1 Users Me Certifications Publisher Get"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/users/me/certifications":{"get":{"tags":["user-certifications"],"summary":"Get all your certifications","description":"Get your current certification status for both Validator and Publisher roles.\n\nReturns:\n    UserCertificationsResponse with both certifications (null if not applied)","operationId":"get_all_certifications_api_v1_users_me_certifications_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCertificationsResponse"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/agents/{chain_id}/{token_id}/views":{"post":{"tags":["page-views"],"summary":"Record Page View","description":"Record a page view for an agent\n\n- **chain_id**: Chain ID (e.g., 11155111 for Sepolia)\n- **token_id**: Token ID from official registry or base58 agent_id (Solana)\n\nThis endpoint can be called by both authenticated and anonymous users.\n\n**Anti-Fraud Protection**:\n- Rate limiting: Max 10 views/min, 100 views/hour, 500 views/day per IP\n- Server-side visitor_id: Generated from IP + User-Agent (cannot be manipulated)\n- Bot detection: Logs suspicious User-Agent patterns\n\n**Deduplication**: Views from the same visitor_id within 24 hours are still counted\nfor total views, but only counted once for unique visitors.","operationId":"record_page_view_api_v1_agents__chain_id___token_id__views_post","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["page-views"],"summary":"Get Agent Views","description":"Get page view statistics for an agent\n\nReturns view counts across different time periods:\n- Total views (all-time)\n- Unique visitors (all-time)\n- Views in last 24 hours\n- Views in last 7 days\n- Views in last 30 days\n\n**Note**: Statistics are real-time from PostgreSQL.","operationId":"get_agent_views_api_v1_agents__chain_id___token_id__views_get","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageViewStatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/{chain_id}/{token_id}/views/history":{"get":{"tags":["page-views"],"summary":"Get Agent Views History","description":"Get daily view counts for an agent (for charts)\n\nReturns daily view counts for the specified time range.\nMissing days are zero-filled for easy chart rendering.\n\n- **chain_id**: Chain ID (e.g., 11155111 for Sepolia)\n- **token_id**: Token ID from official registry or base58 agent_id (Solana)\n- **days**: Number of days to return (default 30, max 90)\n\nExample response:\n```json\n{\n  \"agent_id\": \"3ba7b27f-...\",\n  \"start_date\": \"2025-12-08\",\n  \"end_date\": \"2026-01-07\",\n  \"total_views\": 150,\n  \"items\": [\n    {\"date\": \"2025-12-08\", \"view_count\": 5},\n    {\"date\": \"2025-12-09\", \"view_count\": 0},\n    ...\n  ]\n}\n```","operationId":"get_agent_views_history_api_v1_agents__chain_id___token_id__views_history_get","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":90,"minimum":1,"description":"Number of days (1-90)","default":30,"title":"Days"},"description":"Number of days (1-90)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailyViewsHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/stars/{chain_id}/{token_id}":{"post":{"tags":["agent-stars"],"summary":"Star Agent By Chain","description":"Star (bookmark/favorite) an agent by natural identifier\n\nRequires authentication. Creates a star record and increments the agent's star count.\n\nParameters:\n- chain_id: Chain ID (e.g., 11155111 for Sepolia)\n- token_id: Token ID from official registry or base58 agent_id (Solana)\n\nReturns:\n    - success: True if starred, False if already starred\n    - message: Status message\n    - star_count: Updated total star count for the agent","operationId":"star_agent_by_chain_api_v1_agents_stars__chain_id___token_id__post","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StarAgentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["agent-stars"],"summary":"Unstar Agent By Chain","description":"Unstar (remove bookmark/favorite) an agent by natural identifier\n\nRequires authentication. Deletes the star record and decrements the agent's star count.\n\nParameters:\n- chain_id: Chain ID (e.g., 11155111 for Sepolia)\n- token_id: Token ID from official registry or base58 agent_id (Solana)\n\nReturns:\n    - success: True if unstarred, False if not starred\n    - message: Status message\n    - star_count: Updated total star count for the agent","operationId":"unstar_agent_by_chain_api_v1_agents_stars__chain_id___token_id__delete","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnstarAgentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/stars/{chain_id}/{token_id}/is-starred":{"get":{"tags":["agent-stars"],"summary":"Check If Starred By Chain","description":"Check if current user has starred an agent by natural identifier\n\nRequires authentication.\n\nParameters:\n- chain_id: Chain ID (e.g., 11155111 for Sepolia)\n- token_id: Token ID from official registry or base58 agent_id (Solana)\n\nReturns:\n    - agent_id: Agent UUID\n    - user_id: User UUID\n    - is_starred: True if starred, False otherwise","operationId":"check_if_starred_by_chain_api_v1_agents_stars__chain_id___token_id__is_starred_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IsStarredResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/user/me/starred":{"get":{"tags":["agent-stars"],"summary":"Get My Starred Agents","description":"Get all agents starred by current user\n\nRequires authentication. Convenience endpoint that uses current user's ID.\n\nReturns paginated list of agents that the user has starred,\nsorted by star date (most recent first).\n\nReturns full AgentResponse objects with all fields (same as /agents endpoint).","operationId":"get_my_starred_agents_api_v1_agents_user_me_starred_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/user/{user_id}/starred":{"get":{"tags":["agent-stars"],"summary":"Get User Starred Agents","description":"Get all agents starred by a user\n\nReturns paginated list of agents that the user has starred,\nsorted by star date (most recent first).\n\nNo authentication required - public endpoint.\n\nReturns full AgentResponse objects with all fields (same as /agents endpoint).","operationId":"get_user_starred_agents_api_v1_agents_user__user_id__starred_get","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/featured":{"get":{"tags":["agent-rankings"],"summary":"Get Featured Agents","description":"Get featured agents for homepage hero carousel\n\n**Tag**: agent-rankings\n**Frontend Scenario**: Homepage Hero Section\n**Cache**: 5 minutes\n**Algorithm**: Curated by platform (is_featured=true) + total_score DESC\n\nReturns agents that have been marked as featured (FeaturedScore.is_featured = True),\nsorted by their calculated featured score in descending order.\n\n**Response**: Uses lightweight AgentSummary schema optimized for list views.\nFor full agent details, use GET /agents/{chain_id}/{token_id}.\n\nFeatured scores use the v5 algorithm with 5 dimensions:\n- Engagement (30%): User satisfaction + community popularity\n- Service (25%): A2A/MCP endpoint quality and health\n- Publisher (20%): Wallet credibility + certification\n- Compliance (15%): ERC-8004 standards compliance\n- Momentum (10%): Freshness + recent activity\n\nHealth check and completeness tier apply as multipliers on total_score.\n\nFilters:\n- chain_id: Filter by blockchain (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)\n- is_testnet: Filter by network type (true=testnet, false=mainnet)\n\nCaching:\n- Response is cached for 5 minutes (offset=0 only)\n- Cache key: cache:featured_agents:{chain_id}:{is_testnet}:{limit}","operationId":"get_featured_agents_api_v1_agents_featured_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID","title":"Chain Id"},"description":"Filter by chain ID"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only. When omitted on public ranking endpoints, mainnet is used by default.","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only. When omitted on public ranking endpoints, mainnet is used by default."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSummaryListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/trending":{"get":{"tags":["agent-rankings"],"summary":"Get Trending Agents","description":"Get trending agents (hot now) - GitHub-style algorithm\n\n**Tag**: agent-rankings\n**Frontend Scenario**: Homepage \"Trending Now\" Section\n**Cache**: 1 minute\n**Algorithm**: GitHub-style trending (view_count + time_decay)\n\n**Response**: Uses lightweight AgentSummary schema optimized for list views.\nFor full agent details, use GET /agents/{chain_id}/{token_id}.\n\n**Simplified Algorithm (Current)**:\n```\ntrending_score = view_count / (hours_since_last_activity + 2)^1.5\n```\n\nThis algorithm:\n- ✅ Favors recently active agents (time decay like Hacker News)\n- ✅ Gives new agents with high views a chance to trend\n- ✅ Prevents stale agents from dominating the list\n- ✅ Natural decay - agents drop off without continuous engagement\n\n**Time Periods**:\n- `24h`: Last 24 hours (default)\n- `7d`: Last 7 days\n- `30d`: Last 30 days\n\n**Sorting**: Results are sorted by trending_score DESC (not just view count).\n\n**Limits**: Maximum 50 agents per request.\n\n**Example Scores**:\n- Agent with 100 views, updated 1 hour ago: score ≈ 19.2\n- Agent with 100 views, updated 24 hours ago: score ≈ 0.76\n- Agent with 200 views, updated 12 hours ago: score ≈ 3.8\n\n**Future Enhancement (TODO)**:\nFull GitHub-style algorithm with growth rate detection:\n- Calculate relative growth vs historical average\n- Incorporate activity_score for quality boost\n- Detect \"unusual spikes\" in activity\nSee page_view_service.py calculate_trending_score() for details\n\nFilters:\n- chain_id: Filter by blockchain (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)\n- is_testnet: Filter by network type (true=testnet, false=mainnet)\n\nCaching:\n- Response is cached for 1 minute (offset=0 only)\n- Cache key: cache:trending_agents:{period}:{chain_id}:{is_testnet}:{limit}","operationId":"get_trending_agents_api_v1_agents_trending_get","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(24h|7d|30d)$","description":"Time period: 24h, 7d, or 30d","default":"24h","title":"Period"},"description":"Time period: 24h, 7d, or 30d"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum number of agents to return","default":10,"title":"Limit"},"description":"Maximum number of agents to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID","title":"Chain Id"},"description":"Filter by chain ID"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only. When omitted on public ranking endpoints, mainnet is used by default.","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only. When omitted on public ranking endpoints, mainnet is used by default."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSummaryListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/leaderboard":{"get":{"tags":["agent-rankings"],"summary":"Get Agent Leaderboard","description":"Get agent leaderboard\n\n**Tag**: agent-rankings\n**Frontend Scenario**: Homepage \"Agent Leaderboard\"\n**Cache**: 5 minutes\n**Algorithm**: Sorted by selected score dimension in descending order\n\n**Response**: Uses lightweight AgentSummary schema optimized for list views.\nFor full agent details, use GET /agents/{chain_id}/{token_id}.\n\nReturns agents with rank information, sorted by the selected score dimension.\n\n**Cross-Chain Grouping** (group_cross_chain parameter):\n- When `true` (default): Agents linked via ERC-8004 `registrations` array are grouped.\n  Only the canonical (highest-scoring) version appears in the leaderboard.\n  Each response item includes `cross_chain_versions` with all linked versions.\n- When `false`: Each chain deployment is shown as a separate entry.\n\nGrouping uses verified cross-chain links (reciprocal declaration or owner match).\nSee ERC-8004 spec for `registrations` array format.\n\n**Sort Options**:\n- `total_score`: Overall quality ranking (default) - 6-dimension weighted score\n- `quality_score`: Best rated agents - Bayesian-averaged feedback ratings\n- `popularity_score`: Most popular agents - stars, views, chats\n- `wallet_score`: Best publisher wallets - wallet credibility metrics\n- `freshness_score`: Newest agents - recency bonus (21-day decay)\n- `activity_score`: Most active agents - recent engagement\n- `validation_score`: (DISABLED) - Professional validations (future)\n\n**Time Periods**:\n- `all`: All-time ranking (default)\n- `7d`: Active in last 7 days\n- `30d`: Active in last 30 days\n- `90d`: Active in last 90 days\n\n**Score Calculation (v5)**:\nTotal score is calculated based on 5 dimensions:\n- Engagement (30%): User satisfaction + community popularity\n- Service (25%): A2A/MCP endpoint quality and health\n- Publisher (20%): Wallet credibility + certification\n- Compliance (15%): ERC-8004 standards compliance\n- Momentum (10%): Freshness + recent activity\n\n**Scoring Modifiers**:\n- Completeness tier determines score ceiling\n- No-service penalty for agents without A2A/MCP endpoints\n\nFilters:\n- chain_id: Filter by blockchain (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)\n- is_testnet: Filter by network type (true=testnet, false=mainnet)\n\n**Caching**:\n- Response is cached for 5 minutes (offset=0 only)\n- Cache key includes group_cross_chain parameter","operationId":"get_agent_leaderboard_api_v1_agents_leaderboard_get","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(7d|30d|90d|all)$","description":"Time period for ranking","default":"all","title":"Period"},"description":"Time period for ranking"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","pattern":"^(total_score|quality_score|popularity_score|activity_score|validation_score|wallet_score|freshness_score)$","description":"Sort by score dimension","default":"total_score","title":"Sort By"},"description":"Sort by score dimension"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID","title":"Chain Id"},"description":"Filter by chain ID"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only. When omitted on public ranking endpoints, mainnet is used by default.","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only. When omitted on public ranking endpoints, mainnet is used by default."},{"name":"group_cross_chain","in":"query","required":false,"schema":{"type":"boolean","description":"Group cross-chain deployments together. When true, agents deployed on multiple chains are grouped and only the highest-scoring version appears in the leaderboard. Per ERC-8004 registrations array specification.","default":true,"title":"Group Cross Chain"},"description":"Group cross-chain deployments together. When true, agents deployed on multiple chains are grouped and only the highest-scoring version appears in the leaderboard. Per ERC-8004 registrations array specification."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSummaryListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/latest":{"get":{"tags":["agent-rankings"],"summary":"Get Latest Agents","description":"Get latest registered agents\n\n**Tag**: agent-rankings\n**Frontend Scenario**: Directory \"Latest\" tab\n**Cache**: 2 minutes\n**Algorithm**: created_at DESC\n\n**Response**: Uses lightweight AgentSummary schema optimized for list views.\nFor full agent details, use GET /agents/{chain_id}/{token_id}.\n\nOptimized endpoint for homepage use - returns recently registered agents.\n\nFilters:\n- chain_id: Filter by blockchain (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)\n- is_testnet: Filter by network type (true=testnet, false=mainnet)\n- is_registered: Filter by ERC-8004 registration status (true=registered only, false=placeholders only, any=all)\n\nCaching:\n- Response is cached for 2 minutes (offset=0 only, when is_registered=\"true\")\n- Cache key: cache:latest_agents:{chain_id}:{is_testnet}:{limit}","operationId":"get_latest_agents_api_v1_agents_latest_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID","title":"Chain Id"},"description":"Filter by chain ID"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only. When omitted on public ranking endpoints, mainnet is used by default.","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only. When omitted on public ranking endpoints, mainnet is used by default."},{"name":"is_registered","in":"query","required":false,"schema":{"type":"string","pattern":"^(true|false|any)$","description":"Filter by ERC-8004 registration status. Per ERC-8004: 'registered agent should have registration file'. true=registered agents only (with metadata URI, default), false=placeholder agents only (no metadata URI), any=all agents (no filter)","default":"true","title":"Is Registered"},"description":"Filter by ERC-8004 registration status. Per ERC-8004: 'registered agent should have registration file'. true=registered agents only (with metadata URI, default), false=placeholder agents only (no metadata URI), any=all agents (no filter)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSummaryListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/most-starred":{"get":{"tags":["agent-rankings"],"summary":"Get Most Starred Agents","description":"Get most starred agents (community favorites)\n\n**Tag**: agent-rankings\n**Frontend Scenario**: Directory \"Most Loved\" section\n**Cache**: 3 minutes\n**Algorithm**: stars DESC + popularity_score\n\n**Response**: Uses lightweight AgentSummary schema optimized for list views.\nFor full agent details, use GET /agents/{chain_id}/{token_id}.\n\nReturns agents sorted by total_stars in descending order.\n\n**Time Periods**:\n- `7d`: Stars received in last 7 days (future)\n- `30d`: Stars received in last 30 days (future)\n- `90d`: Stars received in last 90 days (future)\n- `all`: All-time stars (default, currently implemented)\n\nNote: Period-based star filtering requires star_history tracking (future enhancement).\n\nFilters:\n- chain_id: Filter by blockchain (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)\n- is_testnet: Filter by network type (true=testnet, false=mainnet)\n\nCaching:\n- Response is cached for 3 minutes (offset=0 only)\n- Cache key: cache:most_starred_agents:{period}:{chain_id}:{is_testnet}:{limit}","operationId":"get_most_starred_agents_api_v1_agents_most_starred_get","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(7d|30d|90d|all)$","description":"Time period for star ranking","default":"all","title":"Period"},"description":"Time period for star ranking"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID","title":"Chain Id"},"description":"Filter by chain ID"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only. When omitted on public ranking endpoints, mainnet is used by default.","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only. When omitted on public ranking endpoints, mainnet is used by default."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSummaryListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/best-wallet":{"get":{"tags":["agent-rankings"],"summary":"Get Best Wallet Agents","description":"Get agents with best X402 wallet integration\n\n**Tag**: agent-rankings\n**Frontend Scenario**: Directory \"Best Payment Integration\"\n**Cache**: 5 minutes\n**Algorithm**: wallet_score DESC (X402 support + quality)\n\n**Response**: Uses lightweight AgentSummary schema optimized for list views.\nFor full agent details, use GET /agents/{chain_id}/{token_id}.\n\nReturns agents with the highest wallet_score, indicating superior X402 payment integration.\n\nWallet score is based on:\n- X402 support (has agent_wallet configured)\n- Wallet metrics (transaction count, age, balance)\n- Wallet quality indicators\n\nFilters:\n- chain_id: Filter by blockchain\n- is_testnet: Filter by network type (true=testnet, false=mainnet)\n- Only returns agents with x402_supported=true\n\nCaching:\n- Response is cached for 5 minutes (offset=0 only)\n- Cache key: cache:best_wallet_agents:{chain_id}:{is_testnet}:{limit}","operationId":"get_best_wallet_agents_api_v1_agents_best_wallet_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID","title":"Chain Id"},"description":"Filter by chain ID"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only. When omitted on public ranking endpoints, mainnet is used by default.","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only. When omitted on public ranking endpoints, mainnet is used by default."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSummaryListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/{chain_id}/{token_id}/quality":{"get":{"tags":["agent-quality"],"summary":"Get Quality Center data for an agent","operationId":"get_agent_quality_api_v1_agents__chain_id___token_id__quality_get","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}},{"name":"history_days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":30,"title":"History Days"}},{"name":"history_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":12,"title":"History Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentQualityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/scores/v5/{chain_id}/{token_id}":{"get":{"tags":["agents"],"summary":"Get Agent Score Details V5","description":"Get v5 score breakdown for an agent (5 dimensions)\n\nParameters:\n- chain_id: Chain ID (e.g., 11155111 for Sepolia, 1 for Mainnet)\n- token_id: Numeric token ID (e.g., 19837) or base58 agent_id (Solana)\n\nExample:\n- GET /api/v1/agents/scores/v5/1/19837\n\nReturns v5 scoring breakdown with 5 dimensions:\n- Engagement (30%): User satisfaction (feedback) + community popularity (stars, views)\n- Service (25%): A2A/MCP endpoint quality, health status\n- Publisher (20%): Wallet credibility + certification status\n- Compliance (15%): ERC-8004 standards compliance, metadata quality\n- Momentum (10%): Freshness bonus + recent activity\n\nNote: Falls back to legacy response if agent hasn't been scored with v5 algorithm yet.","operationId":"get_agent_score_details_v5_api_v1_agents_scores_v5__chain_id___token_id__get","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentScoreDetailsV5Response"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/score-history/{chain_id}/{token_id}":{"get":{"tags":["agents"],"summary":"Get Agent Score History","description":"Get score history for an agent\n\nParameters:\n- chain_id: Chain ID (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)\n- token_id: Numeric token ID (e.g., 4464) or base58 agent_id (Solana)\n\nExample:\n- GET /api/v1/agents/score-history/11155111/4464?days=30\n\nReturns historical score data points for trend analysis and visualization.","operationId":"get_agent_score_history_api_v1_agents_score_history__chain_id___token_id__get","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Number of days to retrieve","default":30,"title":"Days"},"description":"Number of days to retrieve"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum number of data points","default":100,"title":"Limit"},"description":"Maximum number of data points"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/verify-endpoint/{chain_id}/{token_id}":{"post":{"tags":["agents"],"summary":"Request Endpoint Verification","description":"Request endpoint domain verification for an agent.\n\nThis endpoint queues a verification task to check if the agent's\nendpoint domain has a valid .well-known/agent-registration.json file\nthat contains matching registration info.\n\nRate limit: Once per hour per agent.\n\nNote: Currently does not require authentication. Owner verification\nwill be added when wallet signature auth is implemented.\n\nERC-8004 Spec Reference: Section 119-124","operationId":"request_endpoint_verification_api_v1_agents_verify_endpoint__chain_id___token_id__post","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationRequestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/{chain_id}/{token_id}/health-check":{"post":{"tags":["agents"],"summary":"Request Owner Agent Health Check","description":"Request an owner-triggered health check for an agent.\n\nThis endpoint only queues the existing asynchronous health-check task. It\ndoes not run external service probes inside the API request path and does\nnot trigger an immediate leaderboard rebuild.","operationId":"request_owner_agent_health_check_api_v1_agents__chain_id___token_id__health_check_post","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerHealthCheckRequestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/{chain_id}/{token_id}/metadata-refresh":{"post":{"tags":["agents"],"summary":"Request Owner Agent Metadata Refresh","description":"Queue a bounded metadata refresh for an owner-controlled agent.","operationId":"request_owner_agent_metadata_refresh_api_v1_agents__chain_id___token_id__metadata_refresh_post","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerMetadataRefreshRequestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/search/semantic":{"get":{"tags":["agents"],"summary":"Semantic Search Agents","description":"Semantic search agents using embedding vectors.\n\nThis endpoint performs hybrid search combining:\n- Full-text search (PostgreSQL tsvector)\n- Semantic search (pgvector embedding similarity)\n\nParameters:\n- q: Search query text\n- semantic_weight: Balance between semantic and full-text search\n  - 0.0 = pure full-text search\n  - 0.5 = balanced hybrid search (default)\n  - 1.0 = pure semantic search\n- similarity_threshold: Minimum similarity score (0-1) for results\n\nReturns:\n- List of agents with similarity_score field\n\nExample:\n- GET /agents/search/semantic?q=trading+bot\n- GET /agents/search/semantic?q=DeFi+agent&semantic_weight=0.8","operationId":"semantic_search_agents_api_v1_agents_search_semantic_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":500,"description":"Search query text","title":"Q"},"description":"Search query text"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID","title":"Chain Id"},"description":"Filter by chain ID"},{"name":"is_active","in":"query","required":false,"schema":{"type":"string","pattern":"^(true|false|any)$","description":"Filter by owner-declared availability: true (default), false, or any.","default":"true","title":"Is Active"},"description":"Filter by owner-declared availability: true (default), false, or any."},{"name":"semantic_weight","in":"query","required":false,"schema":{"type":"number","maximum":1.0,"minimum":0.0,"description":"Weight for semantic vs full-text search (0=pure text, 1=pure semantic)","default":0.5,"title":"Semantic Weight"},"description":"Weight for semantic vs full-text search (0=pure text, 1=pure semantic)"},{"name":"similarity_threshold","in":"query","required":false,"schema":{"type":"number","maximum":1.0,"minimum":0.0,"description":"Minimum similarity score for semantic search results","default":0.5,"title":"Similarity Threshold"},"description":"Minimum similarity score for semantic search results"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/{chain_id}/{token_id}":{"get":{"tags":["agents"],"summary":"Get Agent By Chain And Token Id","description":"Get agent by chain_id and token_id (official registry) - cached 60s\n\nThis endpoint queries agents from the official ERC-8004 registry contract.\nFor custom registry contracts, use the 3-parameter endpoint.\n\nParameters:\n- chain_id: Chain ID (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)\n- token_id: Numeric token ID (e.g., 4464) or base58 agent_id (Solana)\n\nExample:\n- GET /api/v1/agents/11155111/4464\n- GET /api/v1/agents/103/5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp...\n\nReturns:\n- Agent details with leaderboard rank (1 = best score)\n\n**Response Fields (Scoring)**:\n- `total_score`: Final weighted score (5-95) after all multipliers applied\n- `scores`: Dimension breakdown (quality, popularity, wallet, metadata, freshness, activity)\n- `quality_score`, `popularity_score`, etc.: Backward-compatible score fields\n\n**Response Fields (Health Check)**:\n- `health_status`: Detailed health check results per service (MCP, A2A, Web)\n- `health_score`: Cached health score (0-100), affects total_score as multiplier\n- `health_checked_at`: Timestamp of last health check\n\n**Cache**: 60 seconds","operationId":"get_agent_by_chain_and_token_id_api_v1_agents__chain_id___token_id__get","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents/{chain_id}/{registry_address}/{token_id}":{"get":{"tags":["agents"],"summary":"Get Agent By Full Identifier","description":"Get agent by full identifier (chain_id, registry_address, token_id)\n\nThis endpoint supports querying agents from custom registry contracts.\nFor official registry, use the simpler 2-parameter endpoint.\n\nParameters:\n- chain_id: Chain ID (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)\n- registry_address: Registry contract address (0x-prefixed, case-insensitive)\n- token_id: Numeric token ID (e.g., 4464)\n\nExample:\n- GET /api/v1/agents/11155111/0x8004a6090cd10a7288092483047b097295fb8847/4464\n\nReturns:\n- Agent details with leaderboard rank (1 = best score)","operationId":"get_agent_by_full_identifier_api_v1_agents__chain_id___registry_address___token_id__get","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"registry_address","in":"path","required":true,"schema":{"type":"string","title":"Registry Address"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"integer","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agents":{"get":{"tags":["agents"],"summary":"List Agents","description":"List all agents with pagination, filtering, sorting, and search\n\nPagination:\n- offset supports shallow UI pagination up to 10,000 rows\n- next_cursor provides index-backed traversal for created_at ordering\n- token_id cursor traversal is available when chain_id is specified\n- cursor requests must keep the same filters, sort_by, and sort_order\n- cursor and offset cannot be combined\n\nSearch Functionality:\n- search: Query string with auto-detection (token_id, agent_id, address, ENS, DID, or full-text)\n  ENS search matches agent endpoint ENS plus cached owner/agent wallet ENS.\n- search_type: Override auto-detection (auto, text, token_id, agent_id, address, ens, did)\n- search_fields: Specify fields for text search (name, description, tags, capabilities, etc.)\n\nBasic Filters:\n- chain_id: Filter by blockchain (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)\n- is_testnet: Filter by network type (true=testnet, false=mainnet)\n- owner_address: Filter by owner Ethereum address (0x...)\n- supported_protocol: Filter agents supporting specific protocol (MCP, A2A, etc.)\n- x402_supported: Filter by X402 payment support (true/false)\n- has_mcp: Filter agents with MCP server endpoint\n- has_a2a: Filter agents with A2A endpoint\n- has_oasf: Filter agents with OASF endpoint\n- is_registered: Filter by ERC-8004 registration status (true=registered only, false=placeholders only, any=all)\n- is_active: Filter by owner-declared availability (true by default)\n\nOASF Filters (support multiple values with OR logic):\n- oasf_skill: Filter by OASF skill(s) - repeat parameter for multiple values\n- oasf_domain: Filter by OASF domain(s) - repeat parameter for multiple values\n\nAdvanced Filters (Phase 1.3):\n- min_feedbacks: Filter agents with at least N feedbacks\n- min_validations: Filter agents with at least N validations\n- min_score: Filter agents with minimum total score (0-100)\n- created_after: Filter agents created after datetime (ISO format)\n- created_before: Filter agents created before datetime (ISO format)\n- tags: Comma-separated tags (OR logic - matches any)\n- categories: Comma-separated categories (OR logic - matches any)\n\nSorting:\n- sort_by: created_at (default), stars, watches, name, total_score\n- sort_order: desc (default), asc\n\nResponse Fields (Scoring):\n- total_score: Final weighted score (5-95) after all multipliers applied\n- scores: Dimension breakdown (quality, popularity, wallet, metadata, freshness, activity)\n- quality_score, popularity_score, etc.: Backward-compatible individual score fields\n\nResponse Fields (Health Check):\n- health_status: Detailed health check results per service (MCP, A2A, Web)\n- health_score: Cached health score (0-100), NULL if never checked\n- health_checked_at: Timestamp of last health check\n\nExamples:\n- GET /agents?search=123 - Find agent with token_id=123\n- GET /agents?search=mcp&search_type=text&search_fields=name - Search \"mcp\" in name only\n- GET /agents?min_score=50 - Get agents with total_score >= 50\n- GET /agents?min_feedbacks=10 - Get agents with at least 10 feedbacks\n- GET /agents?created_after=2025-01-01T00:00:00Z - Get agents created in 2025\n- GET /agents?tags=trading,bot - Get agents tagged with \"trading\" OR \"bot\"\n- GET /agents?categories=DeFi - Get agents in DeFi category\n- GET /agents?min_score=50&chain_id=11155111 - Combine multiple filters\n- GET /agents?has_oasf=true - Get agents with OASF endpoint\n- GET /agents?is_registered=true - Get registered agents only (default, filters out placeholders)\n- GET /agents?is_registered=any - Get all agents including placeholders\n- GET /agents?oasf_skill=Natural%20Language%20Processing - Filter by single OASF skill\n- GET /agents?oasf_skill=NLP&oasf_skill=Data%20Analysis - Filter by multiple skills (OR)\n- GET /agents?oasf_domain=finance - Filter by single OASF domain\n- GET /agents?oasf_domain=finance&oasf_domain=healthcare - Filter by multiple domains (OR)\n- GET /agents?sort_by=total_score&sort_order=desc - Sort by highest score","operationId":"list_agents_api_v1_agents_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Offset for shallow pagination (maximum 10000). Use next_cursor for full traversal.","default":0,"title":"Offset"},"description":"Offset for shallow pagination (maximum 10000). Use next_cursor for full traversal."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1024},{"type":"null"}],"description":"Opaque cursor returned by the previous page. Supported with created_at sorting, or token_id sorting when chain_id is provided.","title":"Cursor"},"description":"Opaque cursor returned by the previous page. Supported with created_at sorting, or token_id sorting when chain_id is provided."},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID","title":"Chain Id"},"description":"Filter by chain ID"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only"},{"name":"owner_publisher_tier","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(OFFICIAL|VERIFIED|COMMUNITY)$"},{"type":"null"}],"description":"Filter by owner's publisher certification tier (OFFICIAL, VERIFIED, COMMUNITY)","title":"Owner Publisher Tier"},"description":"Filter by owner's publisher certification tier (OFFICIAL, VERIFIED, COMMUNITY)"},{"name":"owner_address","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":32,"maxLength":44},{"type":"null"}],"description":"Filter by owner address","title":"Owner Address"},"description":"Filter by owner address"},{"name":"supported_protocol","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by supported protocol (MCP, A2A, etc.)","title":"Supported Protocol"},"description":"Filter by supported protocol (MCP, A2A, etc.)"},{"name":"x402_supported","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by X402 payment support","title":"X402 Supported"},"description":"Filter by X402 payment support"},{"name":"is_active","in":"query","required":false,"schema":{"type":"string","pattern":"^(true|false|any)$","description":"Filter by owner-declared availability (ERC-8004 active field): true (default), false, or any. Inactive identities remain available by direct lookup.","default":"true","title":"Is Active"},"description":"Filter by owner-declared availability (ERC-8004 active field): true (default), false, or any. Inactive identities remain available by direct lookup."},{"name":"is_endpoint_verified","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by endpoint domain verification status","title":"Is Endpoint Verified"},"description":"Filter by endpoint domain verification status"},{"name":"supported_trust","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by supported trust model (reputation, crypto-economic, tee-attestation)","title":"Supported Trust"},"description":"Filter by supported trust model (reputation, crypto-economic, tee-attestation)"},{"name":"has_mcp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter agents with MCP server","title":"Has Mcp"},"description":"Filter agents with MCP server"},{"name":"has_a2a","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter agents with A2A endpoint","title":"Has A2A"},"description":"Filter agents with A2A endpoint"},{"name":"has_oasf","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter agents with OASF endpoint","title":"Has Oasf"},"description":"Filter agents with OASF endpoint"},{"name":"is_registered","in":"query","required":false,"schema":{"type":"string","pattern":"^(true|false|any)$","description":"Filter by ERC-8004 registration status. Per ERC-8004: 'registered agent should have registration file'. - 'true' (default): Registered agents with valid metadata URI. Automatically excludes agents with obvious defects (missing name, test domains like localhost/example.com, invalid URI format). - 'false': Placeholder agents without metadata URI. - 'any': All agents including placeholders and defective ones.","default":"true","title":"Is Registered"},"description":"Filter by ERC-8004 registration status. Per ERC-8004: 'registered agent should have registration file'. - 'true' (default): Registered agents with valid metadata URI. Automatically excludes agents with obvious defects (missing name, test domains like localhost/example.com, invalid URI format). - 'false': Placeholder agents without metadata URI. - 'any': All agents including placeholders and defective ones."},{"name":"oasf_skill","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by OASF skill(s). Supports multiple values (OR logic). Example: ?oasf_skill=NLP&oasf_skill=Data%20Analysis","title":"Oasf Skill"},"description":"Filter by OASF skill(s). Supports multiple values (OR logic). Example: ?oasf_skill=NLP&oasf_skill=Data%20Analysis"},{"name":"oasf_domain","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by OASF domain(s). Supports multiple values (OR logic). Example: ?oasf_domain=finance&oasf_domain=healthcare","title":"Oasf Domain"},"description":"Filter by OASF domain(s). Supports multiple values (OR logic). Example: ?oasf_domain=finance&oasf_domain=healthcare"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","description":"\nSort by field. Available options:\n- Basic: created_at, stars, name, token_id\n- Scores: total_score, quality_score, popularity_score, activity_score, validation_score, wallet_score, freshness_score, metadata_completeness_score\n- Stats: total_feedbacks, average_score, total_validations\n        ","default":"created_at","title":"Sort By"},"description":"\nSort by field. Available options:\n- Basic: created_at, stars, name, token_id\n- Scores: total_score, quality_score, popularity_score, activity_score, validation_score, wallet_score, freshness_score, metadata_completeness_score\n- Stats: total_feedbacks, average_score, total_validations\n        "},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","pattern":"^(asc|desc)$","description":"Sort order: asc or desc","default":"desc","title":"Sort Order"},"description":"Sort order: asc or desc"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}],"description":"\nSearch query with auto-detection support:\n- Numeric (e.g., \"123\") → Search by token_id\n- Address (e.g., \"0x1234...\" or Solana base58) → Search by owner address (Solana also matches agent asset pubkey)\n- Agent ID (e.g., \"11155111:0x8004...:123\") → Search by composite ID\n- ENS (e.g., \"vitalik.eth\") → Search by agent endpoint ENS, owner wallet ENS, or agent wallet ENS\n- DID (e.g., \"did:example:123\") → Search by DID\n- Text → Full-text search across agent data\n        ","title":"Search"},"description":"\nSearch query with auto-detection support:\n- Numeric (e.g., \"123\") → Search by token_id\n- Address (e.g., \"0x1234...\" or Solana base58) → Search by owner address (Solana also matches agent asset pubkey)\n- Agent ID (e.g., \"11155111:0x8004...:123\") → Search by composite ID\n- ENS (e.g., \"vitalik.eth\") → Search by agent endpoint ENS, owner wallet ENS, or agent wallet ENS\n- DID (e.g., \"did:example:123\") → Search by DID\n- Text → Full-text search across agent data\n        "},{"name":"search_type","in":"query","required":false,"schema":{"type":"string","pattern":"^(auto|text|token_id|agent_id|address|ens|did)$","description":"\nSearch type override (auto-detected by default):\n- auto: Auto-detect based on query format (default)\n- text: Full-text search\n- token_id: Numeric token ID\n- agent_id: Composite agent ID (chain:registry:token)\n- address: Ethereum address (owner)\n- ens: ENS name (agent endpoint, owner wallet, or agent wallet)\n- did: Decentralized Identifier\n        ","default":"auto","title":"Search Type"},"description":"\nSearch type override (auto-detected by default):\n- auto: Auto-detect based on query format (default)\n- text: Full-text search\n- token_id: Numeric token ID\n- agent_id: Composite agent ID (chain:registry:token)\n- address: Ethereum address (owner)\n- ens: ENS name (agent endpoint, owner wallet, or agent wallet)\n- did: Decentralized Identifier\n        "},{"name":"search_fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"\nComma-separated list of fields to search (for text search only):\nname, description, tags, categories, capabilities, endpoints, supported_protocols\nExample: \"name,description\" or \"capabilities\"\n        ","title":"Search Fields"},"description":"\nComma-separated list of fields to search (for text search only):\nname, description, tags, categories, capabilities, endpoints, supported_protocols\nExample: \"name,description\" or \"capabilities\"\n        "},{"name":"min_feedbacks","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Filter agents with at least this many feedbacks","title":"Min Feedbacks"},"description":"Filter agents with at least this many feedbacks"},{"name":"min_validations","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Filter agents with at least this many validations","title":"Min Validations"},"description":"Filter agents with at least this many validations"},{"name":"min_score","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":100,"minimum":0},{"type":"null"}],"description":"Filter agents with at least this total score (0-100)","title":"Min Score"},"description":"Filter agents with at least this total score (0-100)"},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter agents created after this datetime (ISO format: 2025-01-01T00:00:00Z)","title":"Created After"},"description":"Filter agents created after this datetime (ISO format: 2025-01-01T00:00:00Z)"},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter agents created before this datetime (ISO format: 2025-12-31T23:59:59Z)","title":"Created Before"},"description":"Filter agents created before this datetime (ISO format: 2025-12-31T23:59:59Z)"},{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated list of tags to filter by (OR logic - matches any tag)","title":"Tags"},"description":"Comma-separated list of tags to filter by (OR logic - matches any tag)"},{"name":"categories","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated list of categories to filter by (OR logic - matches any category)","title":"Categories"},"description":"Comma-separated list of categories to filter by (OR logic - matches any category)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSummaryListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/wallets/{address}":{"get":{"tags":["wallets"],"summary":"Get Wallet","description":"Get comprehensive wallet information by Ethereum address (cached 120s)\n\nReturns:\n- Basic info (address, ENS name, balance)\n- User association (if wallet is linked to a user account)\n- Agent statistics (owned agents, stars, feedbacks, average score)\n- Wallet metrics (transaction count, X402 payments)\n- Most popular agent\n\nThe address is case-insensitive and will be normalized to lowercase.\n\nReturns 404 if no wallet data or agents are found for this address.\n\n**Cache**: 120 seconds\n\nExamples:\n- GET /wallets/0x1234...abcd\n- GET /wallets/vitalik.eth (ENS resolution not supported, use resolved address)","operationId":"get_wallet_api_v1_wallets__address__get","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","title":"Address"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__schemas__wallet__WalletResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/wallets/{address}/agents":{"get":{"tags":["wallets"],"summary":"Get Wallet Agents","description":"Get all agents owned by a wallet address\n\nReturns a paginated list of agents created by this wallet owner.\n\nSorting options:\n- created_at: Sort by on-chain registration date (default)\n- score: Sort by total score\n- stars: Sort by star count\n- name: Sort by agent name\n\nNote: This is equivalent to GET /agents?owner_address=xxx but provides\na more convenient endpoint for wallet profile pages.\n\nExamples:\n- GET /wallets/0x1234...abcd/agents\n- GET /wallets/0x1234...abcd/agents?sort_by=score&sort_order=desc","operationId":"get_wallet_agents_api_v1_wallets__address__agents_get","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","title":"Address"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","description":"Sort by field: created_at, score, stars, name","default":"created_at","title":"Sort By"},"description":"Sort by field: created_at, score, stars, name"},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","pattern":"^(asc|desc)$","description":"Sort order: asc or desc","default":"desc","title":"Sort Order"},"description":"Sort order: asc or desc"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletAgentsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/wallets/{address}/stats":{"get":{"tags":["wallets"],"summary":"Get Wallet Stats","description":"Get detailed statistics for a wallet address (cached 120s)\n\nReturns comprehensive statistics including:\n- Agent counts (total, active, inactive)\n- Protocol distribution (how many agents per protocol type)\n- Quality metrics (average quality and validation scores)\n- Feedback statistics (total, average rating, rating distribution)\n- Engagement metrics (total stars and watches)\n\nThis endpoint provides detailed analytics for agents owned by this address.\n\nReturns 404 if no agents are found for this address.\n\n**Cache**: 120 seconds\n\nExamples:\n- GET /wallets/0x1234...abcd/stats","operationId":"get_wallet_stats_api_v1_wallets__address__stats_get","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","title":"Address"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletStatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/wallets/{address}/metrics":{"get":{"tags":["wallets"],"summary":"Get Wallet Metrics","description":"Get detailed on-chain metrics for a wallet address (cached 120s)\n\nReturns comprehensive on-chain data including:\n- Balance and transaction counts\n- Wallet age (days since first transaction)\n- X402 payment metrics\n- Address classification (is_contract, is_agent_wallet)\n- Associated agents (as owner or agent_wallet)\n\nThis endpoint provides blockchain-level metrics for wallet scoring.\n\nReturns 404 if no metrics are found for this address.\n\n**Cache**: 120 seconds\n\nExamples:\n- GET /wallets/0x1234...abcd/metrics","operationId":"get_wallet_metrics_api_v1_wallets__address__metrics_get","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","title":"Address"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletMetricsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/feedbacks":{"get":{"tags":["feedbacks"],"summary":"List Feedbacks","description":"List feedbacks with pagination and filtering.\n\n**Filters:**\n- agent_id: Filter by agent UUID (internal ID)\n- agent_token_id + chain_id: Filter by agent's on-chain token ID\n- user_address: Filter by user wallet address\n- min_score/max_score: Filter by score range (0-100)\n- include_revoked: Include revoked feedbacks (default: false)\n- tag1/tag2: Filter by ERC-8004 tags (case-insensitive partial match)\n- chain_id: Filter by blockchain network\n- is_testnet: Filter by network type (true=testnet, false=mainnet)\n- oasf_skill: Filter by OASF skill(s) (supports multiple values with OR logic)\n- oasf_domain: Filter by OASF domain(s) (supports multiple values with OR logic)\n\n**Examples:**\n- Get feedbacks for agent #1675 on Sepolia:\n  `GET /feedbacks?chain_id=11155111&agent_token_id=1675`\n- Get all feedbacks from a user:\n  `GET /feedbacks?user_address=0x7a1591...`\n- Get high-score feedbacks:\n  `GET /feedbacks?min_score=90&sort_by=score&sort_order=desc`\n- Get feedbacks related to DeFi:\n  `GET /feedbacks?oasf_domain=finance&oasf_domain=business`\n\n**Optional: include_replies=true** to embed replies (up to 10 per feedback).\nUse `/feedbacks/{id}/replies` for full pagination when `replies.has_more=true`.","operationId":"list_feedbacks_api_v1_feedbacks_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"},{"name":"agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by agent UUID (internal ID)","title":"Agent Id"},"description":"Filter by agent UUID (internal ID)"},{"name":"agent_token_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by agent token ID (use with chain_id)","title":"Agent Token Id"},"description":"Filter by agent token ID (use with chain_id)"},{"name":"user_address","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by user wallet address","title":"User Address"},"description":"Filter by user wallet address"},{"name":"min_score","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"description":"Minimum score filter","title":"Min Score"},"description":"Minimum score filter"},{"name":"max_score","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"description":"Maximum score filter","title":"Max Score"},"description":"Maximum score filter"},{"name":"include_revoked","in":"query","required":false,"schema":{"type":"boolean","description":"Include revoked feedbacks","default":false,"title":"Include Revoked"},"description":"Include revoked feedbacks"},{"name":"tag1","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"description":"Filter by tag1 (case-insensitive partial match, max 255 characters)","title":"Tag1"},"description":"Filter by tag1 (case-insensitive partial match, max 255 characters)"},{"name":"tag2","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"description":"Filter by tag2 (case-insensitive partial match, max 255 characters)","title":"Tag2"},"description":"Filter by tag2 (case-insensitive partial match, max 255 characters)"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID","title":"Chain Id"},"description":"Filter by chain ID"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only"},{"name":"oasf_skill","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":20},{"type":"null"}],"description":"Filter by OASF skill(s). Supports multiple values (OR logic, max 20). Example: ?oasf_skill=NLP&oasf_skill=Data%20Analysis","examples":[["NLP","Data Analysis"]],"title":"Oasf Skill"},"description":"Filter by OASF skill(s). Supports multiple values (OR logic, max 20). Example: ?oasf_skill=NLP&oasf_skill=Data%20Analysis"},{"name":"oasf_domain","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":20},{"type":"null"}],"description":"Filter by OASF domain(s). Supports multiple values (OR logic, max 20). Example: ?oasf_domain=finance&oasf_domain=healthcare","examples":[["finance","healthcare"]],"title":"Oasf Domain"},"description":"Filter by OASF domain(s). Supports multiple values (OR logic, max 20). Example: ?oasf_domain=finance&oasf_domain=healthcare"},{"name":"sort_by","in":"query","required":false,"schema":{"enum":["submitted_at","score","created_at"],"type":"string","description":"Sort by field","default":"submitted_at","title":"Sort By"},"description":"Sort by field"},{"name":"sort_order","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"Sort order","default":"desc","title":"Sort Order"},"description":"Sort order"},{"name":"include_replies","in":"query","required":false,"schema":{"type":"boolean","description":"Include embedded replies (up to 10 per feedback). Default: false","default":false,"title":"Include Replies"},"description":"Include embedded replies (up to 10 per feedback). Default: false"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/feedbacks/{feedback_id}/replies":{"get":{"tags":["feedbacks"],"summary":"Get Feedback Replies","description":"Get paginated replies for a feedback (ERC-8004 appendResponse).\n\nUse this endpoint when `replies.has_more=true` in the feedback detail response.\n\n**Path parameter - feedback_id:**\n\nComposite ID format: `{chain_id}:{agent_token_id}:{client_address}:{feedback_index}`\n\n| Component | Description | Example |\n|-----------|-------------|---------|\n| chain_id | Blockchain network ID | 11155111 (Sepolia) |\n| agent_token_id | ERC-8004 agent NFT token ID | 123 |\n| client_address | User wallet address who submitted feedback | 0x6c96...37f3 |\n| feedback_index | Sequential index (0-based) from this client to this agent | 5 |\n\n**Query parameters:**\n- limit: Number of replies per page (1-500, default: 100)\n- offset: Pagination offset (default: 0)\n\n**ERC-8004 appendResponse allows:**\n- Agent owner to respond with refund proof\n- Third parties to tag feedback as spam\n- Multiple replies per feedback\n\n**Example:**\n```\nGET /feedbacks/11155111:123:0x6c9667ad4ecdcbc1743b5cb2c40b4f8a6bbb37f3:5/replies?limit=50&offset=0\n```","operationId":"get_feedback_replies_api_v1_feedbacks__feedback_id__replies_get","parameters":[{"name":"feedback_id","in":"path","required":true,"schema":{"type":"string","description":"Feedback composite ID: {chain_id}:{agent_token_id}:{client_address}:{feedback_index}","examples":["11155111:123:0x6c9667ad4ecdcbc1743b5cb2c40b4f8a6bbb37f3:5"],"title":"Feedback Id"},"description":"Feedback composite ID: {chain_id}:{agent_token_id}:{client_address}:{feedback_index}"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Number of items per page","default":100,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackReplyListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/feedbacks/{feedback_id}":{"get":{"tags":["feedbacks"],"summary":"Get Feedback","description":"Get feedback by composite ID with embedded replies.\n\n**Path parameter - feedback_id:**\n\nComposite ID format: `{chain_id}:{agent_token_id}:{client_address}:{feedback_index}`\n\n| Component | Description | Example |\n|-----------|-------------|---------|\n| chain_id | Blockchain network ID | 11155111 (Sepolia) |\n| agent_token_id | ERC-8004 agent NFT token ID | 123 |\n| client_address | User wallet address who submitted feedback | 0x6c96...37f3 |\n| feedback_index | Sequential index (0-based) from this client to this agent | 5 |\n\n**Response includes:**\n- Full feedback details with tags, offchain_data, endpoint\n- Embedded replies (up to 10 most recent)\n- `replies.has_more`: If true, use `/feedbacks/{id}/replies` for full pagination\n\n**Example:**\n```\nGET /feedbacks/11155111:123:0x6c9667ad4ecdcbc1743b5cb2c40b4f8a6bbb37f3:5\n```\n\nNOTE: For paginated replies, use GET /feedbacks/{feedback_id}/replies endpoint.","operationId":"get_feedback_api_v1_feedbacks__feedback_id__get","parameters":[{"name":"feedback_id","in":"path","required":true,"schema":{"type":"string","description":"Feedback composite ID: {chain_id}:{agent_token_id}:{client_address}:{feedback_index}","examples":["11155111:123:0x6c9667ad4ecdcbc1743b5cb2c40b4f8a6bbb37f3:5"],"title":"Feedback Id"},"description":"Feedback composite ID: {chain_id}:{agent_token_id}:{client_address}:{feedback_index}"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stats/global":{"get":{"tags":["stats"],"summary":"Get Global Stats","description":"Get platform global statistics (cached 120s)\n\nReturns counts and metrics across the entire platform including:\n- Total counts for agents, users, validators, feedbacks, validations\n- 24-hour activity metrics\n- Average quality scores\n- Supported chains list with deployment status\n- Per-chain detailed statistics\n- Protocol distribution\n\nFilters:\n- is_testnet: Filter by network type (true=testnet, false=mainnet)\n- is_registered: Filter by ERC-8004 registration status (true=registered only, false=placeholders only, any=all)\n\n**Cache**: 120 seconds (reduces repeated database queries per request)","operationId":"get_global_stats_api_v1_stats_global_get","parameters":[{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only"},{"name":"is_registered","in":"query","required":false,"schema":{"type":"string","pattern":"^(true|false|any)$","description":"Filter by ERC-8004 registration status. Per ERC-8004: 'registered agent should have registration file'. true=registered agents only (with metadata URI, default), false=placeholder agents only (no metadata URI), any=all agents (no filter)","default":"true","title":"Is Registered"},"description":"Filter by ERC-8004 registration status. Per ERC-8004: 'registered agent should have registration file'. true=registered agents only (with metadata URI, default), false=placeholder agents only (no metadata URI), any=all agents (no filter)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalStatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stats/daily":{"get":{"tags":["stats"],"summary":"Get Daily Stats","description":"Get platform daily statistics for a date range\n\nReturns historical daily statistics including:\n- New entities (agents, users, validators)\n- Daily activity (feedbacks, validations, chats, messages)\n- Active users metrics\n- Quality metrics\n- Cumulative totals\n\nMaximum date range: 365 days","operationId":"get_daily_stats_api_v1_stats_daily_get","parameters":[{"name":"from_date","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":true,"schema":{"type":"string","format":"date","description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailyStatsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stats/growth":{"get":{"tags":["stats"],"summary":"Get Growth Analysis","description":"Get growth trend analysis for a specific metric\n\nAnalyzes growth trends over time including:\n- Daily values\n- Growth rates (day-over-day %)\n- Total growth in period\n- Average growth rate\n\nSupported metrics:\n- agents: Total agents count\n- users: Total users count\n- feedbacks: Total feedbacks count\n- validations: Total validations count\n\nSupported periods:\n- 7d: Last 7 days\n- 30d: Last 30 days\n- 90d: Last 90 days\n- all: All time data","operationId":"get_growth_analysis_api_v1_stats_growth_get","parameters":[{"name":"metric","in":"query","required":true,"schema":{"type":"string","description":"Metric type: agents, users, feedbacks, validations","title":"Metric"},"description":"Metric type: agents, users, feedbacks, validations"},{"name":"period","in":"query","required":false,"schema":{"type":"string","description":"Time period: 7d, 30d, 90d, all","default":"30d","title":"Period"},"description":"Time period: 7d, 30d, 90d, all"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrowthAnalysisResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stats/growth/chains":{"get":{"tags":["stats"],"summary":"Get Chain Growth","description":"Get per-chain growth data (cached 120s)\n\nReturns time-series data for each chain showing agent and feedback\ncount growth over time. Data is extracted from daily statistics\nchain_stats JSONB field.\n\nSupported periods:\n- 7d: Last 7 days\n- 30d: Last 30 days (default)\n- 90d: Last 90 days\n- all: All time data\n\nOptional filters:\n- chain_id: Get growth data for a specific chain only\n- is_testnet: Filter by testnet (true) or mainnet (false) chains\n\n**Cache**: 120 seconds","operationId":"get_chain_growth_api_v1_stats_growth_chains_get","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","description":"Time period: 7d, 30d, 90d, all","default":"30d","title":"Period"},"description":"Time period: 7d, 30d, 90d, all"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by specific chain ID","title":"Chain Id"},"description":"Filter by specific chain ID"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by testnet status","title":"Is Testnet"},"description":"Filter by testnet status"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChainGrowthResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stats/agents/{chain_id}/{token_id}":{"get":{"tags":["stats"],"summary":"Get Agent Stats","description":"Get statistics for a specific agent (real-time)\n\nParameters:\n- chain_id: Chain ID (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)\n- token_id: Numeric token ID (e.g., 4464) or base58 agent_id (Solana)\n\nExample:\n- GET /api/v1/stats/agents/11155111/4464\n\nReturns comprehensive agent statistics including:\n- Engagement metrics (feedbacks, validations, chats, messages)\n- Social metrics (stars, watches)\n- Quality metrics (average scores)\n- Ranking information\n- Last activity timestamp","operationId":"get_agent_stats_api_v1_stats_agents__chain_id___token_id__get","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentStatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stats/agents/{chain_id}/{token_id}/analytics":{"get":{"tags":["stats"],"summary":"Get Agent Analytics","description":"Get daily analytics for a specific agent\n\nParameters:\n- chain_id: Chain ID (e.g., 11155111 for Sepolia, 84532 for Base Sepolia)\n- token_id: Numeric token ID (e.g., 4464) or base58 agent_id (Solana)\n\nExample:\n- GET /api/v1/stats/agents/11155111/4464/analytics?period=30d\n\nReturns historical daily analytics including:\n- Daily activity (feedbacks, validations, chats, messages, stars)\n- User engagement (unique feedback users, unique chat users)\n- Quality metrics (average scores)\n- Browsing data (page views, unique visitors)\n\nSupported periods:\n- 7d: Last 7 days\n- 30d: Last 30 days (default)\n- 90d: Last 90 days\n- all: All time data","operationId":"get_agent_analytics_api_v1_stats_agents__chain_id___token_id__analytics_get","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}},{"name":"period","in":"query","required":false,"schema":{"type":"string","description":"Time period: 7d, 30d, 90d, all","default":"30d","title":"Period"},"description":"Time period: 7d, 30d, 90d, all"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAnalyticsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stats/feedbacks":{"get":{"tags":["stats"],"summary":"Get Feedback Stats","description":"Get comprehensive feedback statistics (cached 120s)\n\nReturns platform-wide feedback metrics including:\n\n**Overview Counts**:\n- Total feedbacks, active feedbacks, revoked feedbacks\n\n**Score Metrics**:\n- Average, min, max, median scores\n- Score distribution by range (0-20, 21-40, etc.)\n\n**Participation Metrics**:\n- Unique users who gave feedback\n- Unique agents that received feedback\n- Average feedbacks per agent\n\n**Chain Distribution**:\n- Per-chain feedback counts and average scores\n\n**Top Tags**:\n- Most frequently used tags (top 10)\n\n**Daily Trends**:\n- Daily feedback counts for last 30 days\n\n**24h Activity**:\n- New feedbacks and revoked feedbacks in last 24 hours\n\nFilters:\n- is_testnet: Filter by network type (true=testnet, false=mainnet)\n\n**Cache**: 120 seconds (reduces 20+ complex aggregation queries)","operationId":"get_feedback_stats_api_v1_stats_feedbacks_get","parameters":[{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackStatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stats/feedbacks/tags":{"get":{"tags":["stats"],"summary":"Get Feedback Tags","description":"Get all feedback tags with usage counts (cached 300s).\n\nReturns distinct tag1 and tag2 values used across all feedbacks,\nalong with their usage counts.\n\n**Use Cases**:\n- Populate tag filter dropdowns in UI\n- Show popular tags for discovery\n- Analyze tag usage patterns\n\n**Response**:\n- tag1_values: Distinct tag1 values with counts\n- tag2_values: Distinct tag2 values with counts\n- all_tags: Combined tags sorted by total count\n- total_feedbacks_with_tags: Feedbacks with at least one tag\n\nFilters:\n- is_testnet: Filter by network type (true=testnet, false=mainnet)\n\n**Cache**: 300 seconds","operationId":"get_feedback_tags_api_v1_stats_feedbacks_tags_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum tags per field","default":100,"title":"Limit"},"description":"Maximum tags per field"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackTagsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stats/oasf/skills":{"get":{"tags":["stats"],"summary":"Get Oasf Skills","description":"Get OASF skills statistics (cached 300s).\n\nReturns all skills used by agents with OASF endpoints.\nEach skill includes `is_standard` flag indicating if it matches\none of the 15 standard OASF skill categories.\n\n**Use Cases**:\n- Populate skill filter dropdowns in UI\n- Show skill distribution across agents\n\n**Response**:\n- used_skills: Skills used by agents (with is_standard flag and category_id)\n- total_agents_with_oasf: Count of agents with OASF endpoint\n\nFilters:\n- is_testnet: Filter by network type (true=testnet, false=mainnet)\n\n**Cache**: 300 seconds (reduces JSONB array traversal queries)","operationId":"get_oasf_skills_api_v1_stats_oasf_skills_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum skills to return","default":100,"title":"Limit"},"description":"Maximum skills to return"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OASFSkillsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stats/oasf/domains":{"get":{"tags":["stats"],"summary":"Get Oasf Domains","description":"Get OASF domains statistics (cached 300s).\n\nReturns all domains used by agents with OASF endpoints.\nEach domain includes `is_standard` flag indicating if it matches\none of the 24 standard OASF domain categories.\n\n**Use Cases**:\n- Populate domain filter dropdowns in UI\n- Show domain distribution across agents\n\n**Response**:\n- used_domains: Domains used by agents (with is_standard flag and category_id)\n- total_agents_with_oasf: Count of agents with OASF endpoint\n\nFilters:\n- is_testnet: Filter by network type (true=testnet, false=mainnet)\n\n**Cache**: 300 seconds (reduces JSONB array traversal queries)","operationId":"get_oasf_domains_api_v1_stats_oasf_domains_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum domains to return","default":100,"title":"Limit"},"description":"Maximum domains to return"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OASFDomainsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/status/summary":{"get":{"tags":["status"],"summary":"Get Summary Status","description":"Get top-level public platform status.","operationId":"get_summary_status_api_v1_status_summary_get","parameters":[{"name":"strict","in":"query","required":false,"schema":{"type":"boolean","description":"Return HTTP 503 when status reaches strict_level.","default":false,"title":"Strict"},"description":"Return HTTP 503 when status reaches strict_level."},{"name":"strict_level","in":"query","required":false,"schema":{"enum":["warning","critical"],"type":"string","description":"warning maps degraded/down/unknown to HTTP 503; critical maps only down/unknown to HTTP 424.","default":"warning","title":"Strict Level"},"description":"warning maps degraded/down/unknown to HTTP 503; critical maps only down/unknown to HTTP 424."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusSummaryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/status/components":{"get":{"tags":["status"],"summary":"Get Component Statuses","description":"Get API, database, Redis, indexer, and task queue status.","operationId":"get_component_statuses_api_v1_status_components_get","parameters":[{"name":"strict","in":"query","required":false,"schema":{"type":"boolean","description":"Return HTTP 503 when status reaches strict_level.","default":false,"title":"Strict"},"description":"Return HTTP 503 when status reaches strict_level."},{"name":"strict_level","in":"query","required":false,"schema":{"enum":["warning","critical"],"type":"string","description":"warning maps degraded/down/unknown to HTTP 503; critical maps only down/unknown to HTTP 424.","default":"warning","title":"Strict Level"},"description":"warning maps degraded/down/unknown to HTTP 503; critical maps only down/unknown to HTTP 424."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComponentsStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/status/indexers":{"get":{"tags":["status"],"summary":"Get Indexer Statuses","description":"Get per-chain indexer freshness status.","operationId":"get_indexer_statuses_api_v1_status_indexers_get","parameters":[{"name":"strict","in":"query","required":false,"schema":{"type":"boolean","description":"Return HTTP 503 when status reaches strict_level.","default":false,"title":"Strict"},"description":"Return HTTP 503 when status reaches strict_level."},{"name":"strict_level","in":"query","required":false,"schema":{"enum":["warning","critical"],"type":"string","description":"warning maps degraded/down/unknown to HTTP 503; critical maps only down/unknown to HTTP 424.","default":"warning","title":"Strict Level"},"description":"warning maps degraded/down/unknown to HTTP 503; critical maps only down/unknown to HTTP 424."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexersStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/status/indexers/direct":{"get":{"tags":["status"],"summary":"Get Direct Indexer Progress","description":"Get fast per-chain direct RPC indexer progress and health.","operationId":"get_direct_indexer_progress_api_v1_status_indexers_direct_get","parameters":[{"name":"strict","in":"query","required":false,"schema":{"type":"boolean","description":"Return HTTP 503 when status reaches strict_level.","default":false,"title":"Strict"},"description":"Return HTTP 503 when status reaches strict_level."},{"name":"strict_level","in":"query","required":false,"schema":{"enum":["warning","critical"],"type":"string","description":"warning maps degraded/down/unknown to HTTP 503; critical maps only down/unknown to HTTP 424.","default":"warning","title":"Strict Level"},"description":"warning maps degraded/down/unknown to HTTP 503; critical maps only down/unknown to HTTP 424."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectIndexersProgressResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/status/freshness":{"get":{"tags":["status"],"summary":"Get Freshness Statuses","description":"Get fast health, wallet, and direct indexing freshness SLO status.","operationId":"get_freshness_statuses_api_v1_status_freshness_get","parameters":[{"name":"strict","in":"query","required":false,"schema":{"type":"boolean","description":"Return HTTP 503 when status reaches strict_level.","default":false,"title":"Strict"},"description":"Return HTTP 503 when status reaches strict_level."},{"name":"strict_level","in":"query","required":false,"schema":{"enum":["warning","critical"],"type":"string","description":"warning maps degraded/down/unknown to HTTP 503; critical maps only down/unknown to HTTP 424.","default":"warning","title":"Strict Level"},"description":"warning maps degraded/down/unknown to HTTP 503; critical maps only down/unknown to HTTP 424."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreshnessStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/status/taskqueue":{"get":{"tags":["status"],"summary":"Get Taskqueue Statuses","description":"Get Celery queue depth and worker heartbeat status.","operationId":"get_taskqueue_statuses_api_v1_status_taskqueue_get","parameters":[{"name":"strict","in":"query","required":false,"schema":{"type":"boolean","description":"Return HTTP 503 when status reaches strict_level.","default":false,"title":"Strict"},"description":"Return HTTP 503 when status reaches strict_level."},{"name":"strict_level","in":"query","required":false,"schema":{"enum":["warning","critical"],"type":"string","description":"warning maps degraded/down/unknown to HTTP 503; critical maps only down/unknown to HTTP 424.","default":"warning","title":"Strict Level"},"description":"warning maps degraded/down/unknown to HTTP 503; critical maps only down/unknown to HTTP 424."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskQueueStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/leaderboards/validators":{"get":{"tags":["leaderboards"],"summary":"Get Validators Leaderboard","description":"Get validators leaderboard\n\n**Tag**: leaderboards\n**Frontend Scenario**: Validators directory and rankings page\n**Cache**: None (future: 5 minutes)\n\nReturns validators ranked by composite score based on:\n- **Total Validations** (40%): Number of validations performed\n- **Approval Rate** (30%): Percentage of approved validations\n- **Response Time** (20%): Average time to respond to requests\n- **Tier Multiplier** (10%): Bonus based on validator tier\n\n**Sort Options**:\n- `total_score`: Composite ranking (default)\n- `total_validations`: Most active validators\n- `approval_rate`: Highest quality validators\n- `response_time`: Fastest responders\n\n**Time Periods**:\n- `all`: All-time ranking (default)\n- `7d`: Last 7 days\n- `30d`: Last 30 days\n- `90d`: Last 90 days\n\n**Tier Filter** (optional):\n- `platform`: Platform validators (+30% bonus)\n- `official`: Official validators (+20% bonus)\n- `verified`: Verified validators (+10% bonus)\n- `community`: Community validators (+5% bonus)\n\n**Network Filter** (optional):\n- `is_testnet=true`: Only testnet chains\n- `is_testnet=false`: Only mainnet chains\n\n**Algorithm Details**: See docs/features/VALIDATORS_PUBLISHERS_LEADERBOARD.md","operationId":"get_validators_leaderboard_api_v1_leaderboards_validators_get","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(7d|30d|90d|all)$","description":"Time period for ranking","default":"all","title":"Period"},"description":"Time period for ranking"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","pattern":"^(total_score|total_validations|approval_rate|response_time)$","description":"Sort dimension","default":"total_score","title":"Sort By"},"description":"Sort dimension"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"Offset"},"description":"Pagination offset"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID","title":"Chain Id"},"description":"Filter by chain ID"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only"},{"name":"tier","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(platform|official|verified|community)$"},{"type":"null"}],"description":"Filter by validator tier","title":"Tier"},"description":"Filter by validator tier"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorLeaderboardResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/leaderboards/publishers":{"get":{"tags":["leaderboards"],"summary":"Get Publishers Leaderboard","description":"Get publishers leaderboard\n\n**Tag**: leaderboards\n**Frontend Scenario**: Publishers/creators directory and rankings page\n**Cache**: None (future: 5 minutes)\n\nReturns publishers (agent owners) ranked by composite score based on:\n- **Agent Quality** (35%): Average total_score of all their agents\n- **Agent Count** (25%): Number of agents published\n- **Community Engagement** (25%): Total stars + watches across agents\n- **Validation Success** (15%): Percentage of agents validated\n\n**Sort Options**:\n- `total_score`: Composite ranking (default)\n- `agent_count`: Most prolific publishers\n- `avg_quality`: Highest quality agents\n- `total_engagement`: Most community engagement\n- `validation_rate`: Best validated agents\n\n**Time Periods**:\n- `all`: All-time ranking (default)\n- `7d`: Agents created in last 7 days\n- `30d`: Agents created in last 30 days\n- `90d`: Agents created in last 90 days\n\n**Min Agents Filter**:\n- Default: 1 (all publishers)\n- Can set higher to filter out small publishers (e.g., min_agents=5)\n\n**Network Filter** (optional):\n- `is_testnet=true`: Only testnet chains\n- `is_testnet=false`: Only mainnet chains\n\n**Algorithm Details**: See docs/features/VALIDATORS_PUBLISHERS_LEADERBOARD.md","operationId":"get_publishers_leaderboard_api_v1_leaderboards_publishers_get","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(7d|30d|90d|all)$","description":"Time period for ranking","default":"all","title":"Period"},"description":"Time period for ranking"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","pattern":"^(total_score|agent_count|avg_quality|total_engagement|validation_rate)$","description":"Sort dimension","default":"total_score","title":"Sort By"},"description":"Sort dimension"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"Offset"},"description":"Pagination offset"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID","title":"Chain Id"},"description":"Filter by chain ID"},{"name":"is_testnet","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by network type: true=testnet chains only, false=mainnet chains only","title":"Is Testnet"},"description":"Filter by network type: true=testnet chains only, false=mainnet chains only"},{"name":"min_agents","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Minimum agent count threshold","default":1,"title":"Min Agents"},"description":"Minimum agent count threshold"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherLeaderboardResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/ipfs/upload":{"post":{"tags":["ipfs"],"summary":"Upload To Ipfs","description":"Upload JSON content to IPFS\n\nThis endpoint uploads arbitrary JSON content to IPFS and returns the Content Identifier (CID).\nThe content can be retrieved later using the /fetch endpoint or any IPFS gateway.\n\n**Authentication Required**: Yes\n\n**Use Cases**:\n- Agent metadata storage\n- Validation proof storage\n- Feedback evidence storage\n- Any decentralized JSON storage need\n\n**Returns**:\n- cid: IPFS Content Identifier (unique hash of the content)\n- uri: IPFS URI in the format ipfs://{cid}\n- gateway_url: Public HTTP gateway URL for accessing content\n\n**Note**: In development mode, a mock CID may be returned if IPFS is not configured.\nIn production, use a dedicated IPFS node or pinning service (e.g., Pinata, NFT.Storage).\n\n**Rate Limit**: 20 requests per hour per user","operationId":"upload_to_ipfs_api_v1_ipfs_upload_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IPFSUploadRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IPFSUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/ipfs/fetch":{"get":{"tags":["ipfs"],"summary":"Fetch From Ipfs","description":"Fetch JSON content from IPFS by CID\n\nRetrieves content from IPFS using the provided Content Identifier (CID).\nThis endpoint tries multiple public IPFS gateways for redundancy.\n\n**Authentication Required**: No (public endpoint)\n\n**Supported CID Formats**:\n- CID only: `QmXx...` or `bafy...`\n- IPFS URI: `ipfs://QmXx...` or `ipfs://bafy...`\n\n**Use Cases**:\n- Retrieving agent metadata\n- Loading validation proofs\n- Accessing feedback evidence\n- General IPFS content fetching\n\n**Gateways Tried** (in order):\n1. ipfs.io (primary)\n2. cloudflare-ipfs.com (fallback)\n3. gateway.pinata.cloud (fallback)\n4. dweb.link (fallback)\n\n**Returns**:\n- cid: The requested Content Identifier\n- content: Retrieved JSON content\n\n**Note**: Content must be valid JSON. Binary files are not supported by this endpoint.\n\n**Common Errors**:\n- 404: Content not found on any gateway (may not be pinned or invalid CID)\n- 500: All gateways failed or content is not valid JSON","operationId":"fetch_from_ipfs_api_v1_ipfs_fetch_get","parameters":[{"name":"cid","in":"query","required":true,"schema":{"type":"string","description":"IPFS Content Identifier (with or without 'ipfs://' prefix)","title":"Cid"},"description":"IPFS Content Identifier (with or without 'ipfs://' prefix)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IPFSFetchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/media/agents/{chain_id}/{token_id}/image":{"get":{"tags":["media"],"summary":"Get Safe Agent Image","description":"Return only a decoded and re-encoded image for the requested agent.","operationId":"get_safe_agent_image_api_v1_media_agents__chain_id___token_id__image_get","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"307":{"description":"Redirect to a sanitized, cached image"},"404":{"description":"No safe image is available"},"503":{"description":"Image processing is temporarily unavailable"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/storage/status":{"get":{"tags":["storage"],"summary":"Get Storage Status","description":"Get storage service status\n\nReturns configuration status and limits.\nNo authentication required.","operationId":"get_storage_status_api_v1_storage_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageStatusResponse"}}}}}}},"/api/v1/storage/upload":{"post":{"tags":["storage"],"summary":"Upload File","description":"Upload a file to storage\n\nFiles are stored with SHA-256 hash as filename, preserving the original extension.\nThis enables:\n- Content integrity verification (hash = filename)\n- Deduplication (same content = same file)\n- IPFS/Web3 compatibility (content-addressable storage)\n\n**File naming**: `{sha256_hash}.{extension}`\nExample: `a1b2c3d4e5f6...64chars...png`\n\n**Limits**:\n- Maximum file size: 10MB (configurable)\n- 10 uploads per hour per user\n- 30 uploads per day per user\n- 50MB total per day per user\n\n**Returns**:\n- hash: SHA-256 hash of content\n- key: Storage object key\n- url: Public URL for accessing the file\n- deduplicated: True if file already existed\n\n**Authentication**: Required\n**Rate Limit**: 10/hour, 30/day, 50MB/day per user","operationId":"upload_file_api_v1_storage_upload_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_file_api_v1_storage_upload_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/storage/file/{file_key}":{"get":{"tags":["storage"],"summary":"Download File","description":"Download a file by its key (hash.extension)\n\n**Parameters**:\n- file_key: Object key in format `{hash}.{ext}` (e.g., `a1b2c3...64chars....png`)\n- download: If true, sets Content-Disposition to force browser download\n\n**Returns**:\n- File content with appropriate Content-Type header\n\n**Note**: For public files, prefer using the public URL directly\n(available from upload response). This endpoint is useful for:\n- Files without public domain configured\n- Generating download responses","operationId":"download_file_api_v1_storage_file__file_key__get","parameters":[{"name":"file_key","in":"path","required":true,"schema":{"type":"string","title":"File Key"}},{"name":"download","in":"query","required":false,"schema":{"type":"boolean","description":"Force download with Content-Disposition","default":false,"title":"Download"},"description":"Force download with Content-Disposition"}],"responses":{"200":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"head":{"tags":["storage"],"summary":"Check File Exists","description":"Check if file exists (HEAD request)\n\nReturns 200 if file exists, 404 if not.\nUseful for lightweight existence checks.","operationId":"check_file_exists_api_v1_storage_file__file_key__head","parameters":[{"name":"file_key","in":"path","required":true,"schema":{"type":"string","title":"File Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/storage/info/{file_key}":{"get":{"tags":["storage"],"summary":"Get File Info","description":"Get file information without downloading content\n\n**Parameters**:\n- file_key: Object key in format `{hash}.{ext}`\n\n**Returns**:\n- File metadata (size, content_type, url)\n- exists: Whether file exists","operationId":"get_file_info_api_v1_storage_info__file_key__get","parameters":[{"name":"file_key","in":"path","required":true,"schema":{"type":"string","title":"File Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageFileInfo"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/storage/hash/{content_hash}":{"get":{"tags":["storage"],"summary":"Get File By Hash","description":"Get file URL by content hash\n\nIf extension is not provided, attempts to find any file with the given hash.\nThis is useful when you know the content hash but not the original extension.\n\n**Parameters**:\n- content_hash: SHA-256 hash (64 hex characters)\n- extension: Optional file extension\n\n**Returns**:\n- Redirect to public URL or file info","operationId":"get_file_by_hash_api_v1_storage_hash__content_hash__get","parameters":[{"name":"content_hash","in":"path","required":true,"schema":{"type":"string","title":"Content Hash"}},{"name":"extension","in":"query","required":false,"schema":{"type":"string","description":"File extension (e.g., png, json)","title":"Extension"},"description":"File extension (e.g., png, json)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/inbox":{"get":{"tags":["inbox"],"summary":"List Inbox Messages","description":"List inbox messages for current user\n\nReturns paginated list of notifications with:\n- Total count\n- Unread count\n- Message list sorted by created_at DESC","operationId":"list_inbox_messages_api_v1_inbox_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":20,"title":"Limit"},"description":"Number of items per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/MessageType"},{"type":"null"}],"description":"Filter by message type","title":"Type"},"description":"Filter by message type"},{"name":"unread_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only return unread messages","default":false,"title":"Unread Only"},"description":"Only return unread messages"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["inbox"],"summary":"Delete Messages","description":"Delete multiple messages\n\nSupports filtering by:\n- Specific message IDs\n- Message type\n- Date (delete before)\n\nIf no filters provided, returns 400 (safety measure)","operationId":"delete_messages_api_v1_inbox_delete","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/DeleteMessagesRequest"},{"type":"null"}],"title":"Request"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteMessagesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/inbox/unread/count":{"get":{"tags":["inbox"],"summary":"Get Unread Count","description":"Get count of unread messages\n\nLightweight endpoint for showing badge count","operationId":"get_unread_count_api_v1_inbox_unread_count_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnreadCountResponse"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/inbox/{message_id}":{"get":{"tags":["inbox"],"summary":"Get Inbox Message","description":"Get a single inbox message by ID\n\nReturns 404 if message not found or not owned by current user","operationId":"get_inbox_message_api_v1_inbox__message_id__get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","title":"Message Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxMessageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["inbox"],"summary":"Delete Message","description":"Delete a single message","operationId":"delete_message_api_v1_inbox__message_id__delete","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","title":"Message Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteMessagesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/inbox/{message_id}/read":{"post":{"tags":["inbox"],"summary":"Mark Message As Read","description":"Mark a single message as read","operationId":"mark_message_as_read_api_v1_inbox__message_id__read_post","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","title":"Message Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkReadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/inbox/read-all":{"post":{"tags":["inbox"],"summary":"Mark All As Read","description":"Mark messages as read\n\nIf message_ids provided, marks those specific messages.\nOtherwise, marks all unread messages as read.","operationId":"mark_all_as_read_api_v1_inbox_read_all_post","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/MarkReadRequest"},{"type":"null"}],"title":"Request"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkReadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/webhooks/register":{"post":{"tags":["webhooks"],"summary":"Register Webhook","description":"Register a new webhook endpoint\n\nReturns:\n- Webhook ID\n- Secret for signature verification (store this securely!)","operationId":"register_webhook_api_v1_webhooks_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRegisterRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRegistrationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/webhooks":{"get":{"tags":["webhooks"],"summary":"List Webhooks","description":"List all webhooks for current user","operationId":"list_webhooks_api_v1_webhooks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/WebhookRegistrationListResponse"},"type":"array","title":"Response List Webhooks Api V1 Webhooks Get"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/webhooks/{webhook_id}":{"get":{"tags":["webhooks"],"summary":"Get Webhook","description":"Get webhook by ID","operationId":"get_webhook_api_v1_webhooks__webhook_id__get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRegistrationListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["webhooks"],"summary":"Update Webhook","description":"Update webhook configuration","operationId":"update_webhook_api_v1_webhooks__webhook_id__patch","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Update Webhook Api V1 Webhooks  Webhook Id  Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["webhooks"],"summary":"Delete Webhook","description":"Delete webhook","operationId":"delete_webhook_api_v1_webhooks__webhook_id__delete","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Webhook Api V1 Webhooks  Webhook Id  Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/webhooks/{webhook_id}/deliveries":{"get":{"tags":["webhooks"],"summary":"List Deliveries","description":"List webhook delivery history","operationId":"list_deliveries_api_v1_webhooks__webhook_id__deliveries_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDeliveryResponse"},"title":"Response List Deliveries Api V1 Webhooks  Webhook Id  Deliveries Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/certifications/validators":{"get":{"tags":["admin-certifications"],"summary":"[DEPRECATED] List validator certifications (admin only)","description":"List all validator certifications with optional filtering by tier and status.\n\nQuery Parameters:\n- tier: Filter by tier (PLATFORM, OFFICIAL, VERIFIED, COMMUNITY)\n- status: Filter by status (pending, approved, rejected, revoked)\n- page: Page number (default 1)\n- limit: Items per page (default 20, max 100)","operationId":"list_validators_api_v1_admin_certifications_validators_get","deprecated":true,"security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"tier","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(PLATFORM|OFFICIAL|VERIFIED|COMMUNITY)$"},{"type":"null"}],"title":"Tier"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(pending|approved|rejected|revoked)$"},{"type":"null"}],"title":"Status"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/certifications/validators/{user_id}/tier":{"put":{"tags":["admin-certifications"],"summary":"[DEPRECATED] Assign or change validator tier (admin only)","description":"Assign or change a validator's tier.\n\nThis can be used to:\n- Approve a pending application and assign a tier\n- Change an existing validator's tier\n- Assign tier to a user without prior application (admin-initiated)\n\nArgs:\n    tier: PLATFORM, OFFICIAL, VERIFIED, or COMMUNITY\n    reason: Reason for tier assignment\n    kyc_verified: Whether KYC verification is complete\n    certification_expires_at: Optional expiration date\n    metadata: Additional metadata (role, organization, etc.)","operationId":"assign_validator_tier_api_v1_admin_certifications_validators__user_id__tier_put","deprecated":true,"security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorCertificationAdminAssign"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorCertificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/certifications/validators/{user_id}/reject":{"post":{"tags":["admin-certifications"],"summary":"[DEPRECATED] Reject validator certification application (admin only)","description":"Reject a pending validator certification application.\n\nThis is used when:\n- Application does not meet requirements\n- Insufficient experience or qualifications\n- Incomplete or inaccurate information provided\n\nNote: Only pending applications can be rejected.\nUse revoke endpoint for approved certifications.","operationId":"reject_validator_certification_api_v1_admin_certifications_validators__user_id__reject_post","deprecated":true,"security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorCertificationAdminReject"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorCertificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/certifications/validators/{user_id}/revoke":{"post":{"tags":["admin-certifications"],"summary":"[DEPRECATED] Revoke validator certification (admin only)","description":"Revoke a validator's certification.\n\nThis removes their validator status and is typically done due to:\n- Poor performance\n- Unethical behavior\n- Request from the validator\n- Policy changes","operationId":"revoke_validator_certification_api_v1_admin_certifications_validators__user_id__revoke_post","deprecated":true,"security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorCertificationAdminRevoke"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorCertificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/certifications/validators/{user_id}/renew":{"post":{"tags":["admin-certifications"],"summary":"[DEPRECATED] Renew validator certification (admin only)","description":"Renew a validator's certification (extend expiration date).\n\nExtends the certification expiration by 1 year from now.","operationId":"renew_validator_certification_api_v1_admin_certifications_validators__user_id__renew_post","deprecated":true,"security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorCertificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/certifications/publishers":{"get":{"tags":["admin-certifications"],"summary":"List publisher certifications (admin only)","description":"List all publisher certifications with optional filtering by tier and status.\n\nQuery Parameters:\n- tier: Filter by tier (OFFICIAL, VERIFIED, COMMUNITY)\n- status: Filter by status (pending, approved, rejected, revoked)\n- page: Page number (default 1)\n- limit: Items per page (default 20, max 100)","operationId":"list_publishers_api_v1_admin_certifications_publishers_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"tier","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(OFFICIAL|VERIFIED|COMMUNITY)$"},{"type":"null"}],"title":"Tier"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(pending|approved|rejected|revoked)$"},{"type":"null"}],"title":"Status"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/certifications/publishers/{user_id}/tier":{"put":{"tags":["admin-certifications"],"summary":"Assign or change publisher tier (admin only)","description":"Assign or change a publisher's tier.\n\n**IMPORTANT**: `contact_verified` must be True for new approvals. This\nconfirms the admin has communicated with the applicant (via email or\nTelegram) and verified their project ownership claim.\n\nTiers:\n- OFFICIAL: Official organizations (Ethereum Foundation, etc.)\n- VERIFIED: KYC-verified publishers\n- COMMUNITY: Regular developers (default)","operationId":"assign_publisher_tier_api_v1_admin_certifications_publishers__user_id__tier_put","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherCertificationAdminAssign"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherCertificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/certifications/publishers/{user_id}/reject":{"post":{"tags":["admin-certifications"],"summary":"Reject publisher certification application (admin only)","description":"Reject a pending publisher certification application.\n\nThis is used when:\n- Application does not meet requirements\n- Organization verification failed\n- Incomplete or inaccurate information provided\n\nNote: Only pending applications can be rejected.\nUse revoke endpoint for approved certifications.","operationId":"reject_publisher_certification_api_v1_admin_certifications_publishers__user_id__reject_post","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherCertificationAdminReject"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherCertificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/certifications/publishers/{user_id}/revoke":{"post":{"tags":["admin-certifications"],"summary":"Revoke publisher certification (admin only)","description":"Revoke a publisher's certification.\n\nThis removes their publisher status.","operationId":"revoke_publisher_certification_api_v1_admin_certifications_publishers__user_id__revoke_post","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherCertificationAdminRevoke"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherCertificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/certifications/publishers/{user_id}/renew":{"post":{"tags":["admin-certifications"],"summary":"Renew publisher certification (admin only)","description":"Renew a publisher's certification (extend expiration date).\n\nExtends the certification expiration by 1 year from now.","operationId":"renew_publisher_certification_api_v1_admin_certifications_publishers__user_id__renew_post","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherCertificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/certifications/publishers/{user_id}/certified-name":{"put":{"tags":["admin-certifications"],"summary":"Set or clear publisher certified name (admin only)","description":"Set or clear the platform-assigned certified name for a publisher.\n\nThis name is NOT editable by the user — it's a platform-controlled\ndisplay name (e.g. 'Uniswap Project Team') shown alongside agents.\n\nThe publisher must have an approved certification to set this.\nSet certified_name to null to clear.","operationId":"set_publisher_certified_name_api_v1_admin_certifications_publishers__user_id__certified_name_put","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherCertifiedNameUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherCertificationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/certifications/audit-logs":{"get":{"tags":["admin-certifications"],"summary":"View certification audit logs (admin only)","description":"View the complete audit log of all certification changes.\n\nUseful for:\n- Tracking who made which certification changes and when\n- Auditing admin actions\n- Investigating disputes or complaints\n- Compliance and record-keeping\n\nQuery Parameters:\n- cert_type: Filter by certification type (VALIDATOR, PUBLISHER)\n- action: Filter by action (CREATED, APPROVED, REJECTED, REVOKED, TIER_CHANGED, RENEWED)\n- user_id: Filter by user (show changes for specific user)\n- page: Page number (default 1)\n- limit: Items per page (default 50, max 200)","operationId":"get_audit_logs_api_v1_admin_certifications_audit_logs_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"cert_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(VALIDATOR|PUBLISHER)$"},{"type":"null"}],"title":"Cert Type"}},{"name":"action","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(CREATED|APPROVED|REJECTED|REVOKED|TIER_CHANGED|RENEWED)$"},{"type":"null"}],"title":"Action"}},{"name":"user_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/storage/lookup/{object_key}":{"get":{"tags":["admin-storage"],"summary":"Reverse lookup: Find who uploaded a file","description":"Find who uploaded a specific file by its object key.\n\nThis is the primary method for investigating potentially abusive uploads.\n\n**Parameters**:\n- object_key: R2 object key in format `{hash}.{ext}` (e.g., `a1b2c3...png`)\n\n**Returns**:\n- Upload record with uploader information (user_id, wallet, IP)\n\n**Requires**: Admin access","operationId":"lookup_file_uploader_api_v1_admin_storage_lookup__object_key__get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"object_key","in":"path","required":true,"schema":{"type":"string","title":"Object Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageUploadInfo"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/storage/by-user/{user_id}":{"get":{"tags":["admin-storage"],"summary":"List all uploads by a user","description":"List all files uploaded by a specific user.\n\nUseful for auditing a user's storage usage or investigating abuse.\n\n**Parameters**:\n- user_id: User UUID to look up\n- limit: Max results (default 100, max 1000)\n- offset: Skip first N results\n\n**Returns**:\n- List of upload records (newest first)\n\n**Requires**: Admin access","operationId":"list_uploads_by_user_api_v1_admin_storage_by_user__user_id__get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageUploadsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/storage/by-wallet/{wallet_address}":{"get":{"tags":["admin-storage"],"summary":"List all uploads by a wallet address","description":"List all files uploaded by a specific wallet address.\n\n**Parameters**:\n- wallet_address: Ethereum wallet address\n- limit: Max results (default 100, max 1000)\n- offset: Skip first N results\n\n**Returns**:\n- List of upload records (newest first)\n\n**Requires**: Admin access","operationId":"list_uploads_by_wallet_api_v1_admin_storage_by_wallet__wallet_address__get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"wallet_address","in":"path","required":true,"schema":{"type":"string","title":"Wallet Address"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageUploadsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/storage/by-ip/{ip_address}":{"get":{"tags":["admin-storage"],"summary":"List all uploads from an IP address","description":"List all files uploaded from a specific IP address.\n\nUseful for detecting abuse from a single source, such as bots or scrapers.\n\n**Parameters**:\n- ip_address: Client IP address\n- limit: Max results (default 100, max 1000)\n- offset: Skip first N results\n\n**Returns**:\n- List of upload records (newest first)\n\n**Requires**: Admin access","operationId":"list_uploads_by_ip_api_v1_admin_storage_by_ip__ip_address__get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"ip_address","in":"path","required":true,"schema":{"type":"string","title":"Ip Address"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageUploadsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/storage/recent":{"get":{"tags":["admin-storage"],"summary":"List recent uploads","description":"List recent uploads across all users.\n\nUseful for monitoring storage activity.\n\n**Parameters**:\n- limit: Max results (default 100, max 1000)\n- offset: Skip first N results\n\n**Returns**:\n- List of upload records (newest first)\n\n**Requires**: Admin access","operationId":"list_recent_uploads_api_v1_admin_storage_recent_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageUploadsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/storage/top-uploaders":{"get":{"tags":["admin-storage"],"summary":"Get top uploaders (abuse detection)","description":"Get users with the most uploads in a time window.\n\nUseful for detecting abuse patterns such as:\n- Bots uploading many files\n- Users exceeding expected usage\n- Single IP addresses with excessive uploads\n\n**Parameters**:\n- hours: Time window (default 24 hours, max 168/1 week)\n- limit: Max results (default 20)\n\n**Returns**:\n- List of top uploaders with counts\n\n**Requires**: Admin access","operationId":"get_top_uploaders_api_v1_admin_storage_top_uploaders_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":168,"minimum":1,"description":"Time window in hours","default":24,"title":"Hours"},"description":"Time window in hours"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopUploadersResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/storage/stats":{"get":{"tags":["admin-storage"],"summary":"Get global storage statistics","description":"Get global storage statistics.\n\n**Returns**:\n- total_files: Total number of uploaded files\n- total_bytes: Total storage used\n- unique_users: Number of unique uploaders\n- unique_ips: Number of unique IP addresses\n\n**Requires**: Admin access","operationId":"get_storage_stats_api_v1_admin_storage_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageStatsResponse"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/admin/storage/user-usage/{user_id}":{"get":{"tags":["admin-storage"],"summary":"Get storage usage for a user","description":"Get storage usage statistics for a specific user.\n\n**Parameters**:\n- user_id: User UUID\n\n**Returns**:\n- file_count: Number of files uploaded\n- total_bytes: Total storage used\n\n**Requires**: Admin access","operationId":"get_user_storage_usage_api_v1_admin_storage_user_usage__user_id__get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserStorageUsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users":{"get":{"tags":["admin-users"],"summary":"List admin users (SUPER admin only)","description":"List all admin users.\n\nThis endpoint only returns users with admin privileges (is_admin=True).\nUse this to view and manage other admins.\n\nQuery Parameters:\n- search: Search by wallet address or username\n- page: Page number (default 1)\n- limit: Items per page (default 20, max 100)","operationId":"list_admin_users_api_v1_admin_users_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search by wallet or username","title":"Search"},"description":"Search by wallet or username"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/grant-admin":{"post":{"tags":["admin-users"],"summary":"Grant admin privileges (admin only)","description":"Grant admin privileges to a user.\n\nThis action is logged in the admin audit log.\n\nArgs:\n    user_id: Target user's UUID\n    reason: Reason for granting admin privileges","operationId":"grant_admin_api_v1_admin_users__user_id__grant_admin_post","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminGrantRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminChangeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/{user_id}/revoke-admin":{"post":{"tags":["admin-users"],"summary":"Revoke admin privileges (admin only)","description":"Revoke admin privileges from a user.\n\nNote: You cannot revoke your own admin privileges.\nThis action is logged in the admin audit log.\n\nArgs:\n    user_id: Target user's UUID\n    reason: Reason for revoking admin privileges","operationId":"revoke_admin_api_v1_admin_users__user_id__revoke_admin_post","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"User Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminRevokeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminChangeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/users/audit-logs":{"get":{"tags":["admin-users"],"summary":"View admin audit logs (admin only)","description":"View the complete audit log of admin privilege changes.\n\nQuery Parameters:\n- action: Filter by action (GRANT_ADMIN, REVOKE_ADMIN)\n- target_user_id: Filter by target user\n- performed_by_user_id: Filter by admin who performed the action\n- page: Page number (default 1)\n- limit: Items per page (default 50, max 200)","operationId":"get_admin_audit_logs_api_v1_admin_users_audit_logs_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"action","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(GRANT_ADMIN|REVOKE_ADMIN)$"},{"type":"null"}],"title":"Action"}},{"name":"target_user_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Target User Id"}},{"name":"performed_by_user_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Performed By User Id"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminAuditLogResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/donations/summary":{"get":{"tags":["admin-donations"],"summary":"Get Donation Summary","description":"Return donation totals for admin reporting.","operationId":"get_donation_summary_api_v1_admin_donations_summary_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Date From"}},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Date To"}},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chain Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminDonationSummaryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/donations":{"get":{"tags":["admin-donations"],"summary":"List Donations","description":"List settled donations for admins.","operationId":"list_donations_api_v1_admin_donations_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"donor_wallet","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Donor Wallet"}},{"name":"payer_wallet","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payer Wallet"}},{"name":"user_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chain Id"}},{"name":"tx_hash","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tx Hash"}},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Date From"}},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Date To"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminDonationListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/leaderboard-review/shadow-ranking":{"get":{"tags":["admin-leaderboard-review"],"summary":"View shadow leaderboard ranking analysis (admin only)","description":"Return a read-only shadow ranking analysis for the leaderboard.\n\nThis endpoint is intended for internal review by admins and BD:\n- compare current leaderboard vs shadow ordering\n- inspect suspicious high-rank agents\n- review evidence and service-integrity tiers before any scoring change","operationId":"get_shadow_leaderboard_review_api_v1_admin_leaderboard_review_shadow_ranking_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":10,"description":"How many canonical agents to analyze","default":100,"title":"Limit"},"description":"How many canonical agents to analyze"},{"name":"show_top","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":10,"description":"How many rows to return in top_rows","default":30,"title":"Show Top"},"description":"How many rows to return in top_rows"},{"name":"is_testnet","in":"query","required":false,"schema":{"type":"boolean","description":"Analyze testnet instead of mainnet","default":false,"title":"Is Testnet"},"description":"Analyze testnet instead of mainnet"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Optional single-chain filter","title":"Chain Id"},"description":"Optional single-chain filter"},{"name":"integrity_tier","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Optional integrity tier filter: healthy, degraded, broken, no-core-service","title":"Integrity Tier"},"description":"Optional integrity tier filter: healthy, degraded, broken, no-core-service"},{"name":"evidence_tier","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Optional evidence tier filter: battle-tested, validated, emerging, early","title":"Evidence Tier"},"description":"Optional evidence tier filter: battle-tested, validated, emerging, early"},{"name":"review_priority","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Optional review priority filter: HIGH, MEDIUM, LOW, NONE","title":"Review Priority"},"description":"Optional review priority filter: HIGH, MEDIUM, LOW, NONE"},{"name":"min_abs_delta","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":0,"description":"Only include rows with |delta| >= this value","default":0,"title":"Min Abs Delta"},"description":"Only include rows with |delta| >= this value"},{"name":"only_suspicious","in":"query","required":false,"schema":{"type":"boolean","description":"When true, only include HIGH/MEDIUM priority review rows","default":false,"title":"Only Suspicious"},"description":"When true, only include HIGH/MEDIUM priority review rows"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeaderboardShadowReviewResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/featured-agents":{"get":{"tags":["admin-featured-agents"],"summary":"List agents with featured status (admin only)","description":"List agents with their featured status for admin management.\n\nAllows filtering, searching, and pagination.","operationId":"list_featured_agents_api_v1_admin_featured_agents_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"is_featured","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by featured status","title":"Is Featured"},"description":"Filter by featured status"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID","title":"Chain Id"},"description":"Filter by chain ID"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search by agent name","title":"Search"},"description":"Search by agent name"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","pattern":"^(total_score|name|chain_id|rank)$","default":"total_score","title":"Sort By"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedAgentListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/featured-agents/{chain_id}/{token_id}":{"put":{"tags":["admin-featured-agents"],"summary":"Set agent featured status (admin only)","description":"Mark or unmark an agent as featured.\n\nFeatured agents appear in the homepage hero carousel.\nThis action is logged in the featured agent audit log.","operationId":"set_featured_status_api_v1_admin_featured_agents__chain_id___token_id__put","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}},{"name":"token_id","in":"path","required":true,"schema":{"type":"integer","title":"Token Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetFeaturedRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetFeaturedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/featured-agents/bulk":{"post":{"tags":["admin-featured-agents"],"summary":"Bulk set featured status (admin only)","description":"Set featured status for multiple agents at once.\n\nMaximum 50 agents per request.","operationId":"bulk_set_featured_api_v1_admin_featured_agents_bulk_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSetFeaturedRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSetFeaturedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}},"/api/v1/admin/featured-agents/audit-logs":{"get":{"tags":["admin-featured-agents"],"summary":"View featured agent audit logs (admin only)","description":"View the complete audit log of featured agent changes.\n\nQuery Parameters:\n- action: Filter by action type\n- chain_id: Filter by chain ID\n- token_id: Filter by token ID\n- page: Page number (default 1)\n- limit: Items per page (default 50, max 200)","operationId":"get_featured_audit_logs_api_v1_admin_featured_agents_audit_logs_get","security":[{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"action","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(SET_FEATURED|UNSET_FEATURED|BULK_SET_FEATURED|BULK_UNSET_FEATURED)$"},{"type":"null"}],"title":"Action"}},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID","title":"Chain Id"},"description":"Filter by chain ID"},{"name":"token_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by token ID","title":"Token Id"},"description":"Filter by token ID"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedAuditLogResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/mcp/tools/search_agents":{"get":{"tags":["mcp","mcp"],"summary":"Search agents by keyword or semantic similarity","description":"Search for AI agents registered on ERC-8004 by keyword, wallet/agent identifiers, ENS, or semantic similarity.\n\n**Parameters:**\n- query: Search text, ENS, address, token ID, agent ID, DID, or natural language\n- chain_id: Filter by blockchain (optional)\n- limit: Max results (1-50, default 10)\n- search_type: \"keyword\" or \"semantic\" (default: keyword)\n\n**Returns:** List of matching agents with basic info and similarity scores.","operationId":"mcp_search_agents","security":[{"XApiKey":[]},{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Search query text","title":"Query"},"description":"Search query text"},{"name":"chain_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter by chain ID (e.g., 1=Ethereum, 11155111=Sepolia)","title":"Chain Id"},"description":"Filter by chain ID (e.g., 1=Ethereum, 11155111=Sepolia)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum number of results","default":10,"title":"Limit"},"description":"Maximum number of results"},{"name":"search_type","in":"query","required":false,"schema":{"enum":["keyword","semantic"],"type":"string","description":"Search type","default":"keyword","title":"Search Type"},"description":"Search type"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key (for SSE clients)","title":"Api Key"},"description":"API key (for SSE clients)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/mcp/tools/get_agent":{"get":{"tags":["mcp","mcp"],"summary":"Get detailed agent information","description":"Get full details of an AI agent including metadata, scores, owner info, and statistics.\n\n**Parameters:**\n- chain_id: Blockchain chain ID where the agent is registered\n- token_id: Agent's token ID on the ERC-8004 registry contract\n\n**Returns:** Complete agent details including endpoints, metadata, and ranking.","operationId":"mcp_get_agent","security":[{"XApiKey":[]},{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"chain_id","in":"query","required":true,"schema":{"type":"integer","description":"Chain ID (e.g., 11155111 for Sepolia)","title":"Chain Id"},"description":"Chain ID (e.g., 11155111 for Sepolia)"},{"name":"token_id","in":"query","required":true,"schema":{"type":"integer","description":"Token ID on the registry contract","title":"Token Id"},"description":"Token ID on the registry contract"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key (for SSE clients)","title":"Api Key"},"description":"API key (for SSE clients)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPAgentDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/mcp/tools/get_agent_feedbacks":{"get":{"tags":["mcp","mcp"],"summary":"Get feedbacks for a specific agent","description":"Get user feedbacks and ratings for a specific agent.\n\n**Parameters:**\n- chain_id: Agent's chain ID\n- token_id: Agent's token ID\n- limit: Max feedbacks to return (1-50, default 20)\n\n**Returns:** List of feedbacks with scores, comments, and timestamps.","operationId":"mcp_get_agent_feedbacks","security":[{"XApiKey":[]},{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"chain_id","in":"query","required":true,"schema":{"type":"integer","description":"Agent's chain ID","title":"Chain Id"},"description":"Agent's chain ID"},{"name":"token_id","in":"query","required":true,"schema":{"type":"integer","description":"Agent's token ID","title":"Token Id"},"description":"Agent's token ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum number of feedbacks","default":20,"title":"Limit"},"description":"Maximum number of feedbacks"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key (for SSE clients)","title":"Api Key"},"description":"API key (for SSE clients)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPFeedbackResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/mcp/tools/star_agent":{"post":{"tags":["mcp","mcp"],"summary":"Star an agent (add to favorites)","description":"Add an agent to the user's starred/favorites list.\n\n**Parameters:**\n- chain_id: Agent's chain ID\n- token_id: Agent's token ID\n\n**Returns:** Success status and updated star count.","operationId":"mcp_star_agent","security":[{"XApiKey":[]},{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"chain_id","in":"query","required":true,"schema":{"type":"integer","description":"Agent's chain ID","title":"Chain Id"},"description":"Agent's chain ID"},{"name":"token_id","in":"query","required":true,"schema":{"type":"integer","description":"Agent's token ID","title":"Token Id"},"description":"Agent's token ID"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key (for SSE clients)","title":"Api Key"},"description":"API key (for SSE clients)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPStarResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/mcp/tools/unstar_agent":{"post":{"tags":["mcp","mcp"],"summary":"Unstar an agent (remove from favorites)","description":"Remove an agent from the user's starred/favorites list.\n\n**Parameters:**\n- chain_id: Agent's chain ID\n- token_id: Agent's token ID\n\n**Returns:** Success status and updated star count.","operationId":"mcp_unstar_agent","security":[{"XApiKey":[]},{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"chain_id","in":"query","required":true,"schema":{"type":"integer","description":"Agent's chain ID","title":"Chain Id"},"description":"Agent's chain ID"},{"name":"token_id","in":"query","required":true,"schema":{"type":"integer","description":"Agent's token ID","title":"Token Id"},"description":"Agent's token ID"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key (for SSE clients)","title":"Api Key"},"description":"API key (for SSE clients)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPStarResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/mcp/tools/get_starred_agents":{"get":{"tags":["mcp","mcp"],"summary":"Get user's starred agents","description":"Get list of all agents the user has starred/favorited.\n\n**Parameters:**\n- limit: Maximum results (1-100, default 50)\n\n**Returns:** List of starred agents with basic info.","operationId":"mcp_get_starred_agents","security":[{"XApiKey":[]},{"XAccessToken":[]},{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of results","default":50,"title":"Limit"},"description":"Maximum number of results"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key (for SSE clients)","title":"Api Key"},"description":"API key (for SSE clients)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPStarredAgentsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"A2AEndpoint":{"properties":{"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version"},"skills":{"items":{"type":"string"},"type":"array","title":"Skills"}},"type":"object","title":"A2AEndpoint","description":"A2A endpoint details"},"APIKeyCreate":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name","description":"Human-readable name for the key"},"tier":{"anyOf":[{"$ref":"#/components/schemas/APITier"},{"type":"null"}],"description":"Deprecated and ignored. API key tier is derived from the user's active subscription.","deprecated":true},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","description":"Permission scopes"},"expires_in_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Expires In Days","description":"Expiration in days (optional)"}},"type":"object","required":["name"],"title":"APIKeyCreate","description":"Schema for creating a new API key"},"APIKeyCreateResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"key":{"type":"string","title":"Key"},"key_prefix":{"type":"string","title":"Key Prefix"},"tier":{"type":"string","title":"Tier"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"warning":{"type":"string","title":"Warning","default":"⚠️ Save this key now! It will not be shown again."}},"type":"object","required":["id","name","key","key_prefix","tier","scopes","created_at","expires_at"],"title":"APIKeyCreateResponse","description":"Schema for API key creation response (includes the actual key)"},"APIKeyResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"key_prefix":{"type":"string","title":"Key Prefix"},"tier":{"type":"string","title":"Tier"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"total_requests":{"type":"integer","title":"Total Requests"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["id","name","key_prefix","tier","scopes","total_requests","last_used_at","is_active","created_at","expires_at"],"title":"APIKeyResponse","description":"Schema for API key response (without the actual key)"},"APIKeyUsageStats":{"properties":{"key_id":{"type":"string","format":"uuid","title":"Key Id"},"total_requests":{"type":"integer","title":"Total Requests"},"daily_breakdown":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Daily Breakdown"},"limits":{"additionalProperties":true,"type":"object","title":"Limits"}},"type":"object","required":["key_id","total_requests","daily_breakdown","limits"],"title":"APIKeyUsageStats","description":"Schema for API key usage statistics"},"APITier":{"type":"string","enum":["anonymous","public","session","free_api","basic","pro","enterprise","admin"],"title":"APITier","description":"API access tiers\n\nPriority order (highest to lowest):\n1. Internal admin tier (ADMIN - no rate limiting)\n2. API Key tiers (ENTERPRISE > PRO > BASIC > FREE_API)\n3. Browser session (SESSION - JWT + browser)\n4. Anonymous browser (PUBLIC - no auth + browser)\n5. Bot/script (ANONYMOUS - no browser headers)"},"ActivityItem":{"properties":{"type":{"type":"string","title":"Type"},"id":{"type":"string","title":"Id"},"agent_id":{"type":"string","title":"Agent Id"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score"},"is_revoked":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Revoked"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"vote":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vote"}},"type":"object","required":["type","id","agent_id","timestamp"],"title":"ActivityItem","description":"Schema for a single activity item in user activity timeline"},"AdminAuditLogEntry":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"target_user_id":{"type":"string","format":"uuid","title":"Target User Id"},"target_wallet":{"type":"string","title":"Target Wallet"},"action":{"type":"string","title":"Action"},"reason":{"type":"string","title":"Reason"},"performed_by_user_id":{"type":"string","format":"uuid","title":"Performed By User Id"},"performed_by_wallet":{"type":"string","title":"Performed By Wallet"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","target_user_id","target_wallet","action","reason","performed_by_user_id","performed_by_wallet","created_at"],"title":"AdminAuditLogEntry","description":"Admin audit log entry"},"AdminAuditLogResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AdminAuditLogEntry"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"limit":{"type":"integer","title":"Limit"}},"type":"object","required":["items","total","page","limit"],"title":"AdminAuditLogResponse","description":"Paginated admin audit log response"},"AdminChangeResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"user_id":{"type":"string","format":"uuid","title":"User Id"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"primary_wallet":{"type":"string","title":"Primary Wallet"},"is_admin":{"type":"boolean","title":"Is Admin"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","user_id","username","primary_wallet","is_admin","message"],"title":"AdminChangeResponse","description":"Response for admin privilege changes"},"AdminDonationListItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id"},"client_payment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Payment Id"},"status":{"type":"string","title":"Status"},"payer_wallet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payer Wallet"},"donor_wallet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Donor Wallet"},"recipient_wallet":{"type":"string","title":"Recipient Wallet"},"chain_id":{"type":"integer","title":"Chain Id"},"network":{"type":"string","title":"Network"},"tx_hash":{"type":"string","title":"Tx Hash"},"token_address":{"type":"string","title":"Token Address"},"token_symbol":{"type":"string","title":"Token Symbol"},"token_decimals":{"type":"integer","title":"Token Decimals"},"amount_usdc":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Usdc"},"amount_usd":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Usd"},"amount_base_units":{"type":"integer","title":"Amount Base Units"},"verification_attempts":{"type":"integer","title":"Verification Attempts"},"verification_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verification Error"},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Settled At"},"verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Verified At"},"failed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Failed At"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","user_id","client_payment_id","status","payer_wallet","donor_wallet","recipient_wallet","chain_id","network","tx_hash","token_address","token_symbol","token_decimals","amount_usdc","amount_usd","amount_base_units","verification_attempts","verification_error","settled_at","verified_at","failed_at","created_at"],"title":"AdminDonationListItem"},"AdminDonationListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AdminDonationListItem"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"AdminDonationListResponse"},"AdminDonationSummaryResponse":{"properties":{"total_amount_usdc":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount Usdc"},"total_count":{"type":"integer","title":"Total Count"},"unique_donor_wallets":{"type":"integer","title":"Unique Donor Wallets"}},"type":"object","required":["total_amount_usdc","total_count","unique_donor_wallets"],"title":"AdminDonationSummaryResponse"},"AdminGrantRequest":{"properties":{"reason":{"type":"string","maxLength":500,"minLength":5,"title":"Reason","description":"Reason for granting admin"}},"type":"object","required":["reason"],"title":"AdminGrantRequest","description":"Request to grant admin privileges"},"AdminRevokeRequest":{"properties":{"reason":{"type":"string","maxLength":500,"minLength":5,"title":"Reason","description":"Reason for revoking admin"}},"type":"object","required":["reason"],"title":"AdminRevokeRequest","description":"Request to revoke admin privileges"},"AdminUserListItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"primary_wallet":{"type":"string","title":"Primary Wallet"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"is_admin":{"type":"boolean","title":"Is Admin"},"admin_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Admin Role"},"is_verified":{"type":"boolean","title":"Is Verified"},"is_banned":{"type":"boolean","title":"Is Banned"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_login_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Login At"}},"type":"object","required":["id","username","primary_wallet","email","is_admin","is_verified","is_banned","created_at","last_login_at"],"title":"AdminUserListItem","description":"Item in admin user list"},"AdminUserListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AdminUserListItem"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"limit":{"type":"integer","title":"Limit"}},"type":"object","required":["items","total","page","limit"],"title":"AdminUserListResponse","description":"Paginated admin user list response"},"AgentAnalyticsItem":{"properties":{"date":{"type":"string","format":"date","title":"Date"},"daily_feedbacks":{"type":"integer","title":"Daily Feedbacks","default":0},"daily_validations":{"type":"integer","title":"Daily Validations","default":0},"daily_chats":{"type":"integer","title":"Daily Chats","default":0},"daily_messages":{"type":"integer","title":"Daily Messages","default":0},"daily_stars":{"type":"integer","title":"Daily Stars","default":0},"unique_feedback_users":{"type":"integer","title":"Unique Feedback Users","default":0},"unique_chat_users":{"type":"integer","title":"Unique Chat Users","default":0},"average_feedback_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Feedback Score"}},"type":"object","required":["date"],"title":"AgentAnalyticsItem","description":"Schema for agent daily analytics"},"AgentAnalyticsResponse":{"properties":{"chain_id":{"type":"integer","title":"Chain Id","description":"Chain ID (e.g., 11155111 for Sepolia)"},"token_id":{"type":"integer","title":"Token Id","description":"Token ID on the chain"},"agent_id":{"type":"string","title":"Agent Id","description":"Composite agent ID (chain_id:registry_address:token_id)"},"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Name"},"period":{"type":"string","title":"Period","description":"Analysis period (7d, 30d, 90d, all)"},"from_date":{"type":"string","format":"date","title":"From Date"},"to_date":{"type":"string","format":"date","title":"To Date"},"data":{"items":{"$ref":"#/components/schemas/AgentAnalyticsItem"},"type":"array","title":"Data"},"total_feedbacks":{"type":"integer","title":"Total Feedbacks","default":0},"total_chats":{"type":"integer","title":"Total Chats","default":0},"total_unique_users":{"type":"integer","title":"Total Unique Users","default":0},"average_daily_feedbacks":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Daily Feedbacks"}},"type":"object","required":["chain_id","token_id","agent_id","period","from_date","to_date","data"],"title":"AgentAnalyticsResponse","description":"Schema for agent analytics response"},"AgentListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AgentResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"AgentListResponse","description":"Schema for paginated agent list (full response - use AgentSummaryListResponse for list views)"},"AgentQualityResponse":{"properties":{"id":{"type":"string","title":"Id"},"agent_id":{"type":"string","title":"Agent Id"},"chain_id":{"type":"integer","title":"Chain Id"},"token_id":{"type":"string","title":"Token Id"},"generated_at":{"type":"string","format":"date-time","title":"Generated At"},"score":{"$ref":"#/components/schemas/QualityScoreSummary"},"score_history":{"$ref":"#/components/schemas/QualityScoreHistorySummary"},"endpoint_health":{"$ref":"#/components/schemas/QualityEndpointHealthSummary"},"metadata_validation":{"$ref":"#/components/schemas/QualityMetadataValidationSummary"},"risk_flags":{"items":{"$ref":"#/components/schemas/QualityRiskFlag"},"type":"array","title":"Risk Flags"}},"type":"object","required":["id","agent_id","chain_id","token_id","generated_at","score","score_history","endpoint_health","metadata_validation"],"title":"AgentQualityResponse"},"AgentResponse":{"properties":{"id":{"type":"string","title":"Id"},"owner_id":{"type":"string","title":"Owner Id"},"owner_address":{"type":"string","title":"Owner Address"},"owner_ens":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Ens","description":"Owner's ENS name if available"},"owner_username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Username","description":"Owner's display username if registered"},"owner_avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Avatar Url","description":"Owner's avatar URL if registered"},"owner_publisher_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Publisher Tier","description":"Owner's active publisher certification tier (OFFICIAL, VERIFIED, COMMUNITY). NULL if not certified."},"owner_certified_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Certified Name","description":"Platform-assigned certified publisher name (e.g. 'Uniswap Project Team'). NULL if not certified."},"creator_address":{"type":"string","title":"Creator Address"},"agent_id":{"type":"string","title":"Agent Id"},"token_id":{"type":"string","title":"Token Id"},"chain_id":{"type":"integer","title":"Chain Id"},"chain_type":{"type":"string","title":"Chain Type","description":"Chain type: evm or solana","default":"evm"},"is_testnet":{"type":"boolean","title":"Is Testnet","description":"Whether this agent is on a testnet (true) or mainnet (false) chain","default":true},"contract_address":{"type":"string","title":"Contract Address"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"agent_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Type"},"is_verified":{"type":"boolean","title":"Is Verified","default":false},"star_count":{"type":"integer","title":"Star Count","default":0},"watch_count":{"type":"integer","title":"Watch Count","default":0},"supported_protocols":{"items":{"type":"string"},"type":"array","title":"Supported Protocols","description":"Supported protocols (MCP, A2A, OASF, Web, Email)"},"agent_wallet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Wallet","description":"Agent's X402 payment wallet (CAIP-10)"},"x402_supported":{"type":"boolean","title":"X402 Supported","description":"Whether agent supports X402 payments","default":false},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"Sanitized agent avatar/image URL"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Agent tags for categorization"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories","description":"Agent categories"},"services":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Services","description":"All protocol services (MCP, A2A, Web, Email, OASF, ENS, DID). Per EIP-8004 spec (Jan 2026). Contains structured service data parsed from metadata."},"scores":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Scores","description":"All dimension scores"},"total_score":{"type":"number","title":"Total Score","description":"Weighted total score (0-100)","default":0.0},"cross_chain_links":{"items":{"$ref":"#/components/schemas/CrossChainLinkResponse"},"type":"array","title":"Cross Chain Links","description":"Verified cross-chain deployment links"},"cross_chain_versions":{"anyOf":[{"items":{"$ref":"#/components/schemas/CrossChainVersionSummary"},"type":"array"},{"type":"null"}],"title":"Cross Chain Versions","description":"All versions of this agent across chains (only in leaderboard with grouping). Includes the canonical version (is_canonical=true) and all linked versions."},"created_block_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Created Block Number","description":"Block number where agent was registered"},"created_tx_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created Tx Hash","description":"Transaction hash of agent registration"},"is_endpoint_verified":{"type":"boolean","title":"Is Endpoint Verified","description":"Whether ANY endpoint domain is verified. For per-service details, see health_status.services","default":false},"endpoint_verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Endpoint Verified At","description":"When endpoint verification last succeeded (first verified domain)"},"endpoint_verified_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint Verified Domain","description":"First verified domain. For all verified domains, see health_status.services"},"endpoint_verification_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint Verification Error","description":"Combined error messages from failed verifications"},"endpoint_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Endpoint Last Checked At","description":"When last verification attempt was made"},"is_active":{"type":"boolean","title":"Is Active","description":"Owner-declared availability from metadata.active (distinct from platform status)","default":true},"supported_trust_models":{"items":{"type":"string"},"type":"array","title":"Supported Trust Models","description":"Supported trust models: reputation, crypto-economic, tee-attestation"},"health_status":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Health Status","description":"Service health check results with domain verification. Structure: {\"overall_status\": \"healthy|degraded|unhealthy|unknown|skipped\", \"health_score\": 85.5, \"services\": {\"a2a\": {\"status\": \"healthy\", \"message\": \"Valid AgentCard\", \"latency_ms\": 150, \"domain\": \"a2a.example.com\", \"domain_verified\": true, \"verification_status\": \"verified\"}, \"web\": {\"status\": \"skipped\", \"message\": \"Service type not health-checked: web\"}}, \"verification_summary\": {\"verified_count\": 1, \"verifiable_count\": 2, \"any_verified\": true}, \"checked_at\": \"2026-02-02T10:00:00Z\"}"},"health_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Health Score","description":"Cached health score (0-100). NULL if never checked. Affects total_score via multiplier: 100=1.0x, 50=0.75x, 0=0.5x"},"health_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Health Checked At","description":"When last health check was performed. Use to determine if cache is stale."},"total_feedbacks":{"type":"integer","title":"Total Feedbacks","description":"Total number of feedbacks received","default":0},"total_validations":{"type":"integer","title":"Total Validations","description":"Total number of validations","default":0},"successful_validations":{"type":"integer","title":"Successful Validations","description":"Number of successful validations","default":0},"average_score":{"type":"number","title":"Average Score","description":"Average feedback score (0-5)","default":0.0},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"Backward-compatible leaderboard rank (1-based). Equivalent to network_rank and scoped to the agent's network (mainnet/testnet), not a mixed global rank."},"network_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Network Rank","description":"Leaderboard rank (1-based) within the agent's network (mainnet/testnet). This is the preferred field for new clients."},"parse_status":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Parse Status","description":"Unified parse status with errors, warnings, and info"},"raw_metadata":{"anyOf":[{"$ref":"#/components/schemas/RawMetadata"},{"type":"null"}],"description":"Raw metadata from on-chain and off-chain sources. The offchain_content field contains the original metadata JSON uploaded by the user, including the original 'services' or 'endpoints' array before parsing. Use this for debugging or displaying raw metadata to advanced users."},"field_sources":{"anyOf":[{"$ref":"#/components/schemas/FieldSourcesData"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Field Sources","description":"Data source for each merged field. Values are 'hardcoded' (contract state), 'onchain' (setMetadata), or 'offchain' (agentURI). Helps frontends understand data provenance and display appropriate UI."},"ens":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ens","description":"ENS name (from endpoints.ens)"},"did":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Did","description":"DID identifier (from endpoints.did)"},"mcp_server":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mcp Server","description":"MCP server URL (from endpoints.mcp.endpoint)"},"mcp_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mcp Version","description":"MCP version (from endpoints.mcp.version)"},"a2a_endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"A2A Endpoint","description":"A2A endpoint URL (from endpoints.a2a.endpoint)"},"a2a_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"A2A Version","description":"A2A version (from endpoints.a2a.version)"},"agent_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Url","description":"Agent URL (from endpoints.agent_url)"},"quality_score":{"type":"number","title":"Quality Score","description":"Quality score (from scores.quality)","default":0.0},"popularity_score":{"type":"number","title":"Popularity Score","description":"Popularity score (from scores.popularity)","default":0.0},"activity_score":{"type":"number","title":"Activity Score","description":"Activity score (from scores.activity)","default":0.0},"wallet_score":{"type":"number","title":"Wallet Score","description":"Wallet score (from scores.wallet)","default":0.0},"freshness_score":{"type":"number","title":"Freshness Score","description":"Freshness score (from scores.freshness)","default":0.0},"metadata_completeness_score":{"type":"number","title":"Metadata Completeness Score","description":"Metadata completeness (from scores.metadata_completeness)","default":0.0},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"On-chain registration timestamp (unified from registered_at)"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","owner_id","owner_address","creator_address","agent_id","token_id","chain_id","contract_address","created_at","updated_at"],"title":"AgentResponse","description":"Schema for agent response"},"AgentScoreDetailsV5Response":{"properties":{"agent_id":{"type":"string","title":"Agent Id"},"agent_name":{"type":"string","title":"Agent Name"},"total_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Total Score","description":"Final weighted score (0-100)"},"last_scored_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Scored At"},"version":{"type":"string","title":"Version","default":"5.2"},"algorithm":{"type":"string","title":"Algorithm","default":"v5_leaderboard_policy"},"engagement":{"anyOf":[{"$ref":"#/components/schemas/V5Dimension"},{"type":"null"}]},"service":{"anyOf":[{"$ref":"#/components/schemas/V5Dimension"},{"type":"null"}]},"publisher":{"anyOf":[{"$ref":"#/components/schemas/V5Dimension"},{"type":"null"}]},"compliance":{"anyOf":[{"$ref":"#/components/schemas/V5Dimension"},{"type":"null"}]},"momentum":{"anyOf":[{"$ref":"#/components/schemas/V5Dimension"},{"type":"null"}]},"multipliers":{"additionalProperties":true,"type":"object","title":"Multipliers"},"raw_scores":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Raw Scores"},"weights":{"additionalProperties":{"type":"number"},"type":"object","title":"Weights","default":{"engagement":0.3,"service":0.25,"publisher":0.2,"compliance":0.15,"momentum":0.1}}},"type":"object","required":["agent_id","agent_name","total_score"],"title":"AgentScoreDetailsV5Response","description":"v5 scoring response with 5 dimensions\n\nDimensions:\n- Engagement (30%): User satisfaction + community popularity\n- Service (25%): A2A/MCP endpoint quality and health\n- Publisher (20%): Wallet credibility + certification\n- Compliance (15%): ERC-8004 standards compliance\n- Momentum (10%): Freshness + recent activity"},"AgentSearchResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AgentSearchResult"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"AgentSearchResponse","description":"Schema for paginated agent search results with similarity scores"},"AgentSearchResult":{"properties":{"id":{"type":"string","title":"Id"},"owner_id":{"type":"string","title":"Owner Id"},"owner_address":{"type":"string","title":"Owner Address"},"owner_ens":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Ens","description":"Owner's ENS name if available"},"owner_username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Username","description":"Owner's display username if registered"},"owner_avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Avatar Url","description":"Owner's avatar URL if registered"},"owner_publisher_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Publisher Tier","description":"Owner's active publisher certification tier (OFFICIAL, VERIFIED, COMMUNITY). NULL if not certified."},"owner_certified_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Certified Name","description":"Platform-assigned certified publisher name (e.g. 'Uniswap Project Team'). NULL if not certified."},"creator_address":{"type":"string","title":"Creator Address"},"agent_id":{"type":"string","title":"Agent Id"},"token_id":{"type":"string","title":"Token Id"},"chain_id":{"type":"integer","title":"Chain Id"},"chain_type":{"type":"string","title":"Chain Type","description":"Chain type: evm or solana","default":"evm"},"is_testnet":{"type":"boolean","title":"Is Testnet","description":"Whether this agent is on a testnet (true) or mainnet (false) chain","default":true},"contract_address":{"type":"string","title":"Contract Address"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"agent_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Type"},"is_verified":{"type":"boolean","title":"Is Verified","default":false},"star_count":{"type":"integer","title":"Star Count","default":0},"watch_count":{"type":"integer","title":"Watch Count","default":0},"supported_protocols":{"items":{"type":"string"},"type":"array","title":"Supported Protocols","description":"Supported protocols (MCP, A2A, OASF, Web, Email)"},"agent_wallet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Wallet","description":"Agent's X402 payment wallet (CAIP-10)"},"x402_supported":{"type":"boolean","title":"X402 Supported","description":"Whether agent supports X402 payments","default":false},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"Sanitized agent avatar/image URL"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Agent tags for categorization"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories","description":"Agent categories"},"services":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Services","description":"All protocol services (MCP, A2A, Web, Email, OASF, ENS, DID). Per EIP-8004 spec (Jan 2026). Contains structured service data parsed from metadata."},"scores":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Scores","description":"All dimension scores"},"total_score":{"type":"number","title":"Total Score","description":"Weighted total score (0-100)","default":0.0},"cross_chain_links":{"items":{"$ref":"#/components/schemas/CrossChainLinkResponse"},"type":"array","title":"Cross Chain Links","description":"Verified cross-chain deployment links"},"cross_chain_versions":{"anyOf":[{"items":{"$ref":"#/components/schemas/CrossChainVersionSummary"},"type":"array"},{"type":"null"}],"title":"Cross Chain Versions","description":"All versions of this agent across chains (only in leaderboard with grouping). Includes the canonical version (is_canonical=true) and all linked versions."},"created_block_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Created Block Number","description":"Block number where agent was registered"},"created_tx_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created Tx Hash","description":"Transaction hash of agent registration"},"is_endpoint_verified":{"type":"boolean","title":"Is Endpoint Verified","description":"Whether ANY endpoint domain is verified. For per-service details, see health_status.services","default":false},"endpoint_verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Endpoint Verified At","description":"When endpoint verification last succeeded (first verified domain)"},"endpoint_verified_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint Verified Domain","description":"First verified domain. For all verified domains, see health_status.services"},"endpoint_verification_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint Verification Error","description":"Combined error messages from failed verifications"},"endpoint_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Endpoint Last Checked At","description":"When last verification attempt was made"},"is_active":{"type":"boolean","title":"Is Active","description":"Owner-declared availability from metadata.active (distinct from platform status)","default":true},"supported_trust_models":{"items":{"type":"string"},"type":"array","title":"Supported Trust Models","description":"Supported trust models: reputation, crypto-economic, tee-attestation"},"health_status":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Health Status","description":"Service health check results with domain verification. Structure: {\"overall_status\": \"healthy|degraded|unhealthy|unknown|skipped\", \"health_score\": 85.5, \"services\": {\"a2a\": {\"status\": \"healthy\", \"message\": \"Valid AgentCard\", \"latency_ms\": 150, \"domain\": \"a2a.example.com\", \"domain_verified\": true, \"verification_status\": \"verified\"}, \"web\": {\"status\": \"skipped\", \"message\": \"Service type not health-checked: web\"}}, \"verification_summary\": {\"verified_count\": 1, \"verifiable_count\": 2, \"any_verified\": true}, \"checked_at\": \"2026-02-02T10:00:00Z\"}"},"health_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Health Score","description":"Cached health score (0-100). NULL if never checked. Affects total_score via multiplier: 100=1.0x, 50=0.75x, 0=0.5x"},"health_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Health Checked At","description":"When last health check was performed. Use to determine if cache is stale."},"total_feedbacks":{"type":"integer","title":"Total Feedbacks","description":"Total number of feedbacks received","default":0},"total_validations":{"type":"integer","title":"Total Validations","description":"Total number of validations","default":0},"successful_validations":{"type":"integer","title":"Successful Validations","description":"Number of successful validations","default":0},"average_score":{"type":"number","title":"Average Score","description":"Average feedback score (0-5)","default":0.0},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"Backward-compatible leaderboard rank (1-based). Equivalent to network_rank and scoped to the agent's network (mainnet/testnet), not a mixed global rank."},"network_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Network Rank","description":"Leaderboard rank (1-based) within the agent's network (mainnet/testnet). This is the preferred field for new clients."},"parse_status":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Parse Status","description":"Unified parse status with errors, warnings, and info"},"raw_metadata":{"anyOf":[{"$ref":"#/components/schemas/RawMetadata"},{"type":"null"}],"description":"Raw metadata from on-chain and off-chain sources. The offchain_content field contains the original metadata JSON uploaded by the user, including the original 'services' or 'endpoints' array before parsing. Use this for debugging or displaying raw metadata to advanced users."},"field_sources":{"anyOf":[{"$ref":"#/components/schemas/FieldSourcesData"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Field Sources","description":"Data source for each merged field. Values are 'hardcoded' (contract state), 'onchain' (setMetadata), or 'offchain' (agentURI). Helps frontends understand data provenance and display appropriate UI."},"ens":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ens","description":"ENS name (from endpoints.ens)"},"did":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Did","description":"DID identifier (from endpoints.did)"},"mcp_server":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mcp Server","description":"MCP server URL (from endpoints.mcp.endpoint)"},"mcp_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mcp Version","description":"MCP version (from endpoints.mcp.version)"},"a2a_endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"A2A Endpoint","description":"A2A endpoint URL (from endpoints.a2a.endpoint)"},"a2a_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"A2A Version","description":"A2A version (from endpoints.a2a.version)"},"agent_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Url","description":"Agent URL (from endpoints.agent_url)"},"quality_score":{"type":"number","title":"Quality Score","description":"Quality score (from scores.quality)","default":0.0},"popularity_score":{"type":"number","title":"Popularity Score","description":"Popularity score (from scores.popularity)","default":0.0},"activity_score":{"type":"number","title":"Activity Score","description":"Activity score (from scores.activity)","default":0.0},"wallet_score":{"type":"number","title":"Wallet Score","description":"Wallet score (from scores.wallet)","default":0.0},"freshness_score":{"type":"number","title":"Freshness Score","description":"Freshness score (from scores.freshness)","default":0.0},"metadata_completeness_score":{"type":"number","title":"Metadata Completeness Score","description":"Metadata completeness (from scores.metadata_completeness)","default":0.0},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"On-chain registration timestamp (unified from registered_at)"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"similarity_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Similarity Score","description":"Semantic similarity score (0-1), only present in semantic search results"}},"type":"object","required":["id","owner_id","owner_address","creator_address","agent_id","token_id","chain_id","contract_address","created_at","updated_at"],"title":"AgentSearchResult","description":"Schema for agent search result with similarity score.\n\nExtends AgentResponse with similarity_score for semantic search results."},"AgentStatsResponse":{"properties":{"chain_id":{"type":"integer","title":"Chain Id","description":"Chain ID (e.g., 11155111 for Sepolia)"},"token_id":{"type":"integer","title":"Token Id","description":"Token ID on the chain"},"agent_id":{"type":"string","title":"Agent Id","description":"Composite agent ID (chain_id:registry_address:token_id)"},"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Name"},"total_feedbacks":{"type":"integer","title":"Total Feedbacks","default":0},"total_validations":{"type":"integer","title":"Total Validations","default":0},"total_chats":{"type":"integer","title":"Total Chats","default":0},"total_messages":{"type":"integer","title":"Total Messages","default":0},"total_stars":{"type":"integer","title":"Total Stars","default":0},"total_watches":{"type":"integer","title":"Total Watches","default":0},"average_feedback_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Feedback Score"},"average_validation_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Validation Score"},"overall_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Overall Score"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"last_active":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Active"}},"type":"object","required":["chain_id","token_id","agent_id"],"title":"AgentStatsResponse","description":"Schema for agent statistics (real-time)"},"AgentSummaryListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/app__schemas__agent__AgentSummary"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque cursor for the next page when cursor traversal is supported"},"has_more":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has More","description":"Whether another page is available"}},"type":"object","required":["items","total","limit","offset"],"title":"AgentSummaryListResponse","description":"Schema for paginated agent list using lightweight AgentSummary"},"AssociatedAgent":{"properties":{"chain_id":{"type":"integer","title":"Chain Id"},"token_id":{"type":"integer","title":"Token Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"role":{"type":"string","title":"Role","description":"Relationship: 'owner' or 'agent_wallet'"}},"type":"object","required":["chain_id","token_id","role"],"title":"AssociatedAgent","description":"Agent associated with a wallet"},"Body_upload_file_api_v1_storage_upload_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"File to upload"}},"type":"object","required":["file"],"title":"Body_upload_file_api_v1_storage_upload_post"},"BulkSetFeaturedRequest":{"properties":{"agent_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":50,"title":"Agent Ids","description":"List of agent UUIDs"},"is_featured":{"type":"boolean","title":"Is Featured","description":"Whether agents should be featured"},"reason":{"type":"string","maxLength":500,"minLength":5,"title":"Reason"}},"type":"object","required":["agent_ids","is_featured","reason"],"title":"BulkSetFeaturedRequest","description":"Bulk set featured status"},"BulkSetFeaturedResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"updated":{"type":"integer","title":"Updated"},"failed":{"type":"integer","title":"Failed"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","updated","failed","message"],"title":"BulkSetFeaturedResponse","description":"Response for bulk operation"},"ChainDetailedStats":{"properties":{"chain_id":{"type":"integer","title":"Chain Id","description":"Chain ID"},"name":{"type":"string","title":"Name","description":"Chain display name"},"is_testnet":{"type":"boolean","title":"Is Testnet","description":"Whether this is a testnet"},"total_agents":{"type":"integer","title":"Total Agents","description":"Total agents on this chain","default":0},"daily_new_agents":{"type":"integer","title":"Daily New Agents","description":"New agents in last 24h","default":0},"total_feedbacks":{"type":"integer","title":"Total Feedbacks","description":"Total feedbacks on this chain","default":0},"daily_feedbacks":{"type":"integer","title":"Daily Feedbacks","description":"Feedbacks in last 24h","default":0},"average_feedback_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Feedback Score","description":"Average feedback score"},"mcp_agents":{"type":"integer","title":"Mcp Agents","description":"Agents with MCP endpoint","default":0},"a2a_agents":{"type":"integer","title":"A2A Agents","description":"Agents with A2A endpoint","default":0},"oasf_agents":{"type":"integer","title":"Oasf Agents","description":"Agents with OASF endpoint","default":0}},"type":"object","required":["chain_id","name","is_testnet"],"title":"ChainDetailedStats","description":"Detailed statistics for a single chain"},"ChainGrowthDataPoint":{"properties":{"date":{"type":"string","format":"date","title":"Date"},"agents":{"type":"integer","title":"Agents","description":"Cumulative agent count on this chain","default":0},"feedbacks":{"type":"integer","title":"Feedbacks","description":"Cumulative feedback count on this chain","default":0}},"type":"object","required":["date"],"title":"ChainGrowthDataPoint","description":"Single data point for per-chain growth"},"ChainGrowthResponse":{"properties":{"period":{"type":"string","title":"Period","description":"Analysis period (7d, 30d, 90d, all)"},"chains":{"items":{"$ref":"#/components/schemas/ChainGrowthSeries"},"type":"array","title":"Chains"}},"type":"object","required":["period","chains"],"title":"ChainGrowthResponse","description":"Response for per-chain growth analysis"},"ChainGrowthSeries":{"properties":{"chain_id":{"type":"integer","title":"Chain Id","description":"Chain ID"},"name":{"type":"string","title":"Name","description":"Chain display name"},"is_testnet":{"type":"boolean","title":"Is Testnet","description":"Whether this is a testnet"},"data":{"items":{"$ref":"#/components/schemas/ChainGrowthDataPoint"},"type":"array","title":"Data"},"total_agents_growth":{"type":"integer","title":"Total Agents Growth","description":"Agent count change over period","default":0},"total_feedbacks_growth":{"type":"integer","title":"Total Feedbacks Growth","description":"Feedback count change over period","default":0}},"type":"object","required":["chain_id","name","is_testnet","data"],"title":"ChainGrowthSeries","description":"Growth time-series for a single chain"},"ChannelSettings":{"properties":{"enabled":{"type":"boolean","title":"Enabled","default":true},"events":{"$ref":"#/components/schemas/EventSettings"}},"type":"object","title":"ChannelSettings","description":"Settings for a notification channel"},"ComponentStatus":{"properties":{"name":{"type":"string","title":"Name"},"status":{"type":"string","enum":["ok","degraded","down","unknown"],"title":"Status"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latency Ms"}},"type":"object","required":["name","status"],"title":"ComponentStatus"},"ComponentsStatusResponse":{"properties":{"status":{"type":"string","enum":["ok","degraded","down","unknown"],"title":"Status"},"checked_at":{"type":"string","format":"date-time","title":"Checked At"},"environment":{"type":"string","title":"Environment"},"version":{"type":"string","title":"Version"},"components":{"items":{"$ref":"#/components/schemas/ComponentStatus"},"type":"array","title":"Components"}},"type":"object","required":["status","checked_at","environment","version","components"],"title":"ComponentsStatusResponse"},"CrossChainLinkResponse":{"properties":{"target_chain_id":{"type":"integer","title":"Target Chain Id","description":"Target chain ID where the cross-chain deployment exists"},"target_registry":{"type":"string","title":"Target Registry","description":"Target registry contract address (checksummed or lowercase)"},"target_token_id":{"type":"string","title":"Target Token Id","description":"Target agent's token ID on the target chain"},"target_agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Agent Id","description":"Target agent base58 ID (Solana cross-chain targets)"},"linked_agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linked Agent Id","description":"UUID of the target agent if found in our database. None if target hasn't been indexed yet."},"verification_status":{"type":"string","title":"Verification Status","description":"Trust level: 'unverified' (not verified), 'reciprocal' (mutual declaration), 'owner_match' (same owner)","default":"unverified"}},"type":"object","required":["target_chain_id","target_registry","target_token_id"],"title":"CrossChainLinkResponse","description":"Cross-chain link representing an agent's declaration of deployment on another chain.\n\nThis schema represents OUTGOING links only - when Agent A declares it exists on Chain B,\nthis creates a cross-chain link FROM Agent A TO the target on Chain B.\n\n## How Cross-Chain Links Work\n\nERC-8004 agents can declare cross-chain deployments via the `registrations` array\nin their metadata JSON. Each registration uses CAIP-2 format:\n```json\n{\n    \"registrations\": [\n        {\"agentId\": 123, \"agentRegistry\": \"eip155:84532:0x1234...\"}\n    ]\n}\n```\n\n## Verification Status Levels\n\nThe verification system establishes trust levels for cross-chain claims:\n\n- **\"unverified\"** (level 0): Target agent not found in our database, or no\n  reciprocal declaration exists. The link is claimed but not verified.\n\n- **\"reciprocal\"** (level 1): Mutual reference - both agents point to each other.\n  Agent A declares Agent B, AND Agent B declares Agent A. This proves both\n  deployments acknowledge each other, but doesn't prove same ownership.\n\n- **\"owner_match\"** (level 2): Highest trust - both agents have the same\n  on-chain owner address. This is the strongest verification since blockchain\n  ownership cannot be faked.\n\n## API Behavior Examples\n\n1. **A declares B, B declares A, same owner**: A's response shows link to B\n   with `verification_status: \"owner_match\"`\n\n2. **A declares B, B declares A, different owner**: A's response shows link to B\n   with `verification_status: \"reciprocal\"`\n\n3. **A declares B, but B doesn't declare A**: A's response shows link to B\n   with `verification_status: \"unverified\"`\n\n4. **B declares A, but A doesn't declare B**: A's response has NO link to B\n   (cross_chain_links only shows OUTGOING declarations from the queried agent)\n\nNote: Self-referential links (agent pointing to itself on same chain) are\nfiltered out during indexing - they represent single-chain deployments."},"CrossChainVersionSummary":{"properties":{"agent_id":{"type":"string","title":"Agent Id","description":"Agent UUID"},"chain_id":{"type":"integer","title":"Chain Id","description":"Chain ID of this version"},"token_id":{"type":"string","title":"Token Id","description":"Token ID on this chain"},"total_score":{"type":"number","title":"Total Score","description":"Score of this version","default":0.0},"total_feedbacks":{"type":"integer","title":"Total Feedbacks","description":"Feedback count of this version","default":0},"is_canonical":{"type":"boolean","title":"Is Canonical","description":"Whether this is the canonical (highest-scoring) version shown in leaderboard","default":false}},"type":"object","required":["agent_id","chain_id","token_id"],"title":"CrossChainVersionSummary","description":"Summary of a cross-chain version for leaderboard grouping.\n\nWhen agents are grouped by cross-chain links in the leaderboard,\nthis schema provides a brief summary of each version (deployment on different chains).\nOnly populated in leaderboard responses when group_cross_chain=true."},"CurrentUserResponse":{"properties":{"id":{"type":"string","title":"Id"},"primary_wallet":{"type":"string","title":"Primary Wallet"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"bio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bio"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"twitter_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twitter Handle"},"github_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Github Handle"},"website_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website Url"},"total_feedbacks":{"type":"integer","title":"Total Feedbacks","default":0},"total_validations_requested":{"type":"integer","title":"Total Validations Requested","default":0},"total_validations_responded":{"type":"integer","title":"Total Validations Responded","default":0},"total_agents_created":{"type":"integer","title":"Total Agents Created","default":0},"email_verified":{"type":"boolean","title":"Email Verified","default":false},"email_verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Email Verified At"},"is_certified_validator":{"type":"boolean","title":"Is Certified Validator","default":false},"is_certified_publisher":{"type":"boolean","title":"Is Certified Publisher","default":false},"validator_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Validator Tier"},"publisher_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publisher Tier"},"publisher_certified_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publisher Certified Name"},"is_verified":{"type":"boolean","title":"Is Verified","default":false},"is_official_validator":{"type":"boolean","title":"Is Official Validator","default":false},"is_admin":{"type":"boolean","title":"Is Admin","default":false},"admin_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Admin Role"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"last_login_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Login At"}},"type":"object","required":["id","primary_wallet","created_at","updated_at"],"title":"CurrentUserResponse","description":"Schema for current user response (extended user info)"},"CurrentUserUpdate":{"properties":{"username":{"anyOf":[{"type":"string","maxLength":50,"minLength":3},{"type":"null"}],"title":"Username"},"email":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Email"},"bio":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Bio"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"twitter_handle":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Twitter Handle"},"github_handle":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Github Handle"},"website_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website Url"}},"type":"object","title":"CurrentUserUpdate","description":"Schema for updating current user profile"},"DailyStatsItem":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Date of statistics"},"new_agents":{"type":"integer","title":"New Agents","default":0},"new_users":{"type":"integer","title":"New Users","default":0},"new_validators":{"type":"integer","title":"New Validators","default":0},"daily_feedbacks":{"type":"integer","title":"Daily Feedbacks","default":0},"daily_validations":{"type":"integer","title":"Daily Validations","default":0},"daily_validation_responses":{"type":"integer","title":"Daily Validation Responses","default":0},"daily_chats":{"type":"integer","title":"Daily Chats","default":0},"daily_messages":{"type":"integer","title":"Daily Messages","default":0},"active_users":{"type":"integer","title":"Active Users","default":0},"active_validators":{"type":"integer","title":"Active Validators","default":0},"active_agents":{"type":"integer","title":"Active Agents","default":0},"average_feedback_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Feedback Score"},"average_validation_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Validation Score"},"average_response_time_hours":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Response Time Hours"},"total_agents_to_date":{"type":"integer","title":"Total Agents To Date","default":0},"total_users_to_date":{"type":"integer","title":"Total Users To Date","default":0},"total_feedbacks_to_date":{"type":"integer","title":"Total Feedbacks To Date","default":0},"total_validations_to_date":{"type":"integer","title":"Total Validations To Date","default":0}},"type":"object","required":["date"],"title":"DailyStatsItem","description":"Schema for a single day's statistics"},"DailyStatsListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/DailyStatsItem"},"type":"array","title":"Items"},"from_date":{"type":"string","format":"date","title":"From Date","description":"Start date"},"to_date":{"type":"string","format":"date","title":"To Date","description":"End date"},"total":{"type":"integer","title":"Total","description":"Total number of days"}},"type":"object","required":["items","from_date","to_date","total"],"title":"DailyStatsListResponse","description":"Schema for daily statistics list response"},"DailyViewItem":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Date (YYYY-MM-DD)"},"view_count":{"type":"integer","minimum":0.0,"title":"View Count","description":"View count for this day"}},"type":"object","required":["date","view_count"],"title":"DailyViewItem","description":"Single day view count for chart data"},"DailyViewsHistoryResponse":{"properties":{"agent_id":{"type":"string","title":"Agent Id","description":"Agent UUID"},"start_date":{"type":"string","format":"date","title":"Start Date","description":"Start date of the range"},"end_date":{"type":"string","format":"date","title":"End Date","description":"End date of the range"},"total_views":{"type":"integer","minimum":0.0,"title":"Total Views","description":"Sum of views in the range"},"items":{"items":{"$ref":"#/components/schemas/DailyViewItem"},"type":"array","title":"Items","description":"Daily view counts"}},"type":"object","required":["agent_id","start_date","end_date","total_views","items"],"title":"DailyViewsHistoryResponse","description":"Response for daily views history (for charts)"},"DeleteMessagesRequest":{"properties":{"message_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Message Ids","description":"Specific message IDs to delete. If None, deletes all."},"message_type":{"anyOf":[{"$ref":"#/components/schemas/MessageType"},{"type":"null"}],"description":"Delete all messages of this type"},"before_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Before Date","description":"Delete messages created before this date"}},"type":"object","title":"DeleteMessagesRequest","description":"Schema for deleting messages"},"DeleteMessagesResponse":{"properties":{"deleted_count":{"type":"integer","title":"Deleted Count"}},"type":"object","required":["deleted_count"],"title":"DeleteMessagesResponse","description":"Schema for delete result"},"DirectIndexerProgressItem":{"properties":{"chain_key":{"type":"string","title":"Chain Key"},"chain_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chain Id"},"chain_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chain Name"},"enabled":{"type":"boolean","title":"Enabled","default":false},"configured":{"type":"boolean","title":"Configured","default":false},"required":{"type":"boolean","title":"Required","default":false},"status":{"type":"string","enum":["ok","degraded","down","unknown"],"title":"Status"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"mode":{"type":"string","title":"Mode"},"rpc_endpoint_count":{"type":"integer","title":"Rpc Endpoint Count","default":0},"warn_after_seconds":{"type":"integer","title":"Warn After Seconds"},"down_after_seconds":{"type":"integer","title":"Down After Seconds"},"canonical_checkpoint_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Canonical Checkpoint Block"},"canonical_checkpoint_age_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Canonical Checkpoint Age Seconds"},"canonical_checkpoint_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Checkpoint Status"},"canonical_last_checkpoint_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Canonical Last Checkpoint At"},"canonical_total_synced":{"type":"integer","title":"Canonical Total Synced","default":0},"canonical_last_sync_duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Canonical Last Sync Duration Ms"},"shadow_checkpoint_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Shadow Checkpoint Block"},"shadow_checkpoint_age_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Shadow Checkpoint Age Seconds"},"latest_event_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latest Event Block"},"blocks_since_latest_event":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Blocks Since Latest Event"},"latest_event_processed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Latest Event Processed At"},"pending_events":{"type":"integer","title":"Pending Events","default":0},"failed_events":{"type":"integer","title":"Failed Events","default":0},"reorged_events":{"type":"integer","title":"Reorged Events","default":0},"rpc_endpoints":{"items":{"$ref":"#/components/schemas/DirectRpcEndpointMetrics"},"type":"array","title":"Rpc Endpoints"}},"type":"object","required":["chain_key","status","mode","warn_after_seconds","down_after_seconds"],"title":"DirectIndexerProgressItem"},"DirectIndexersProgressResponse":{"properties":{"status":{"type":"string","enum":["ok","degraded","down","unknown"],"title":"Status"},"checked_at":{"type":"string","format":"date-time","title":"Checked At"},"mode":{"type":"string","title":"Mode"},"enabled":{"type":"boolean","title":"Enabled"},"status_required":{"type":"boolean","title":"Status Required"},"poll_interval_seconds":{"type":"number","title":"Poll Interval Seconds"},"event_status_count_cap":{"type":"integer","title":"Event Status Count Cap"},"indexers":{"items":{"$ref":"#/components/schemas/DirectIndexerProgressItem"},"type":"array","title":"Indexers"},"totals":{"$ref":"#/components/schemas/DirectIndexersProgressTotals"}},"type":"object","required":["status","checked_at","mode","enabled","status_required","poll_interval_seconds","event_status_count_cap","indexers","totals"],"title":"DirectIndexersProgressResponse"},"DirectIndexersProgressTotals":{"properties":{"chains":{"type":"integer","title":"Chains"},"configured_chains":{"type":"integer","title":"Configured Chains"},"required_chains":{"type":"integer","title":"Required Chains"},"ok":{"type":"integer","title":"Ok"},"degraded":{"type":"integer","title":"Degraded"},"down":{"type":"integer","title":"Down"},"unknown":{"type":"integer","title":"Unknown"},"pending_events":{"type":"integer","title":"Pending Events"},"failed_events":{"type":"integer","title":"Failed Events"},"reorged_events":{"type":"integer","title":"Reorged Events"},"canonical_total_synced":{"type":"integer","title":"Canonical Total Synced"},"rpc_calls_1m":{"type":"integer","title":"Rpc Calls 1M","default":0},"rpc_errors_1m":{"type":"integer","title":"Rpc Errors 1M","default":0},"rpc_qps_1m":{"type":"number","title":"Rpc Qps 1M","default":0.0},"rpc_avg_latency_ms_1m":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rpc Avg Latency Ms 1M"},"rpc_calls_5m":{"type":"integer","title":"Rpc Calls 5M","default":0},"rpc_errors_5m":{"type":"integer","title":"Rpc Errors 5M","default":0},"rpc_qps_5m":{"type":"number","title":"Rpc Qps 5M","default":0.0},"rpc_avg_latency_ms_5m":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rpc Avg Latency Ms 5M"}},"type":"object","required":["chains","configured_chains","required_chains","ok","degraded","down","unknown","pending_events","failed_events","reorged_events","canonical_total_synced"],"title":"DirectIndexersProgressTotals"},"DirectRpcEndpointMetrics":{"properties":{"endpoint_index":{"type":"integer","title":"Endpoint Index"},"endpoint_host":{"type":"string","title":"Endpoint Host"},"calls_1m":{"type":"integer","title":"Calls 1M","default":0},"errors_1m":{"type":"integer","title":"Errors 1M","default":0},"qps_1m":{"type":"number","title":"Qps 1M","default":0.0},"error_rate_1m":{"type":"number","title":"Error Rate 1M","default":0.0},"avg_latency_ms_1m":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Latency Ms 1M"},"calls_5m":{"type":"integer","title":"Calls 5M","default":0},"errors_5m":{"type":"integer","title":"Errors 5M","default":0},"qps_5m":{"type":"number","title":"Qps 5M","default":0.0},"error_rate_5m":{"type":"number","title":"Error Rate 5M","default":0.0},"avg_latency_ms_5m":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Latency Ms 5M"},"methods":{"items":{"$ref":"#/components/schemas/DirectRpcMethodMetrics"},"type":"array","title":"Methods"}},"type":"object","required":["endpoint_index","endpoint_host"],"title":"DirectRpcEndpointMetrics"},"DirectRpcMethodMetrics":{"properties":{"method":{"type":"string","title":"Method"},"calls_1m":{"type":"integer","title":"Calls 1M","default":0},"errors_1m":{"type":"integer","title":"Errors 1M","default":0},"qps_1m":{"type":"number","title":"Qps 1M","default":0.0},"avg_latency_ms_1m":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Latency Ms 1M"},"calls_5m":{"type":"integer","title":"Calls 5M","default":0},"errors_5m":{"type":"integer","title":"Errors 5M","default":0},"qps_5m":{"type":"number","title":"Qps 5M","default":0.0},"avg_latency_ms_5m":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Latency Ms 5M"}},"type":"object","required":["method"],"title":"DirectRpcMethodMetrics"},"DonationConfigResponse":{"properties":{"chain_id":{"type":"integer","title":"Chain Id"},"network":{"type":"string","title":"Network"},"chain_name":{"type":"string","title":"Chain Name"},"is_testnet":{"type":"boolean","title":"Is Testnet"},"facilitator":{"type":"string","title":"Facilitator"},"token_symbol":{"type":"string","title":"Token Symbol"},"token_address":{"type":"string","title":"Token Address"},"token_decimals":{"type":"integer","title":"Token Decimals"},"recipient_wallet":{"type":"string","title":"Recipient Wallet"},"min_amount_usd":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Min Amount Usd"},"max_amount_usd":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Max Amount Usd"},"preset_amounts_usd":{"items":{"type":"string"},"type":"array","title":"Preset Amounts Usd"},"explorer_tx_base_url":{"type":"string","title":"Explorer Tx Base Url"}},"type":"object","required":["chain_id","network","chain_name","is_testnet","facilitator","token_symbol","token_address","token_decimals","recipient_wallet","min_amount_usd","max_amount_usd","preset_amounts_usd","explorer_tx_base_url"],"title":"DonationConfigResponse"},"DonationLeaderboardItem":{"properties":{"rank":{"type":"integer","title":"Rank"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"display_wallet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Wallet"},"tier":{"type":"string","title":"Tier"},"total_amount_usdc":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount Usdc"},"total_amount_display":{"type":"string","title":"Total Amount Display"},"donation_count":{"type":"integer","title":"Donation Count"},"last_donated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Donated At"},"is_registered_user":{"type":"boolean","title":"Is Registered User"}},"type":"object","required":["rank","user_id","display_name","avatar_url","display_wallet","tier","total_amount_usdc","total_amount_display","donation_count","last_donated_at","is_registered_user"],"title":"DonationLeaderboardItem"},"DonationLeaderboardResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/DonationLeaderboardItem"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"DonationLeaderboardResponse"},"DonationPayRequest":{"properties":{"amount_usd":{"type":"string","title":"Amount Usd","description":"Donation amount in USD/USDC, up to 2 decimals"},"chain_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chain Id","description":"Donation settlement chain ID"},"client_payment_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Client Payment Id","description":"Optional frontend-generated idempotency/status handle"}},"type":"object","required":["amount_usd"],"title":"DonationPayRequest"},"DonationStatusResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"client_payment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Payment Id"},"status":{"type":"string","title":"Status"},"amount_usdc":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Usdc"},"amount_usd":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Usd"},"chain_id":{"type":"integer","title":"Chain Id"},"network":{"type":"string","title":"Network"},"tx_hash":{"type":"string","title":"Tx Hash"},"explorer_url":{"type":"string","title":"Explorer Url"},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Settled At"},"verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Verified At"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","client_payment_id","status","amount_usdc","amount_usd","chain_id","network","tx_hash","explorer_url","settled_at","verified_at","created_at"],"title":"DonationStatusResponse"},"EmailEndpoint":{"properties":{"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint"}},"type":"object","title":"EmailEndpoint","description":"Email endpoint for human contact"},"EmailUpdateRequest":{"properties":{"email":{"type":"string","pattern":"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$","title":"Email"}},"type":"object","required":["email"],"title":"EmailUpdateRequest","description":"Request to update email"},"EmailVerificationRequest":{"properties":{"verification_code":{"type":"string","title":"Verification Code"}},"type":"object","required":["verification_code"],"title":"EmailVerificationRequest","description":"Request to verify email with code"},"EmailVerificationResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"},"email_verified":{"type":"boolean","title":"Email Verified"},"email_verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Email Verified At"}},"type":"object","required":["success","message","email_verified","email_verified_at"],"title":"EmailVerificationResponse","description":"Response after email verification"},"EmbeddedReplies":{"properties":{"items":{"items":{"$ref":"#/components/schemas/FeedbackReply"},"type":"array","title":"Items","description":"Recent replies (up to 10)"},"total":{"type":"integer","title":"Total","description":"Total number of replies"},"has_more":{"type":"boolean","title":"Has More","description":"Whether there are more replies beyond the embedded limit"}},"type":"object","required":["items","total","has_more"],"title":"EmbeddedReplies","description":"Embedded replies in FeedbackDetail with pagination info"},"EndpointsData":{"properties":{"mcp":{"anyOf":[{"$ref":"#/components/schemas/MCPEndpoint"},{"type":"null"}]},"a2a":{"anyOf":[{"$ref":"#/components/schemas/A2AEndpoint"},{"type":"null"}]},"oasf":{"anyOf":[{"$ref":"#/components/schemas/OASFEndpoint"},{"type":"null"}]},"web":{"anyOf":[{"$ref":"#/components/schemas/WebEndpoint"},{"type":"null"}]},"email":{"anyOf":[{"$ref":"#/components/schemas/EmailEndpoint"},{"type":"null"}]},"ens":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ens"},"did":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Did"},"agent_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Url"}},"type":"object","title":"EndpointsData","description":"All protocol services - stored in 'endpoints' JSONB column, exposed as 'services' in API\n\nThis contains STANDARDIZED service data parsed from the original metadata's\n'services' (EIP-8004 Jan 2026+) or 'endpoints' (legacy) array.\n\nDatabase vs API naming:\n- Database column: 'endpoints' (internal, not exposed)\n- API field: 'services' (per EIP-8004 spec)\n\nNOTE: This only contains services array data from ERC-8004 spec.\nOther top-level fields like supportedTrust and registrations are NOT stored here:\n- supportedTrust: stored in metadata_json (top-level)\n- registrations: normalized into AgentCrossChainLink table"},"EventSettings":{"properties":{"feedback_received":{"type":"boolean","title":"Feedback Received","default":true},"feedback_revoked":{"type":"boolean","title":"Feedback Revoked","default":true},"validation_requested":{"type":"boolean","title":"Validation Requested","default":true},"validation_completed":{"type":"boolean","title":"Validation Completed","default":true},"star_received":{"type":"boolean","title":"Star Received","default":true},"star_removed":{"type":"boolean","title":"Star Removed","default":false},"watch_received":{"type":"boolean","title":"Watch Received","default":false},"watch_removed":{"type":"boolean","title":"Watch Removed","default":false},"agent_updated":{"type":"boolean","title":"Agent Updated","default":true},"new_follower":{"type":"boolean","title":"New Follower","default":true},"follower_lost":{"type":"boolean","title":"Follower Lost","default":false},"system_announcement":{"type":"boolean","title":"System Announcement","default":true}},"type":"object","title":"EventSettings","description":"Per-event notification settings"},"FeaturedAgentListItem":{"properties":{"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"chain_id":{"type":"integer","title":"Chain Id"},"token_id":{"type":"integer","title":"Token Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"total_score":{"type":"number","title":"Total Score"},"is_featured":{"type":"boolean","title":"Is Featured"},"featured_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Featured Score"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"chain_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chain Rank"},"calculated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Calculated At"}},"type":"object","required":["agent_id","chain_id","token_id","name","total_score","is_featured","featured_score","rank","chain_rank","calculated_at"],"title":"FeaturedAgentListItem","description":"Featured agent list item"},"FeaturedAgentListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/FeaturedAgentListItem"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"limit":{"type":"integer","title":"Limit"}},"type":"object","required":["items","total","page","limit"],"title":"FeaturedAgentListResponse","description":"Paginated featured agents list"},"FeaturedAuditLogItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"chain_id":{"type":"integer","title":"Chain Id"},"token_id":{"type":"integer","title":"Token Id"},"agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Name"},"action":{"type":"string","title":"Action"},"reason":{"type":"string","title":"Reason"},"performed_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Performed By User Id"},"performed_by_wallet":{"type":"string","title":"Performed By Wallet"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","chain_id","token_id","agent_name","action","reason","performed_by_user_id","performed_by_wallet","created_at"],"title":"FeaturedAuditLogItem","description":"Audit log item for featured agent operations"},"FeaturedAuditLogResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/FeaturedAuditLogItem"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"limit":{"type":"integer","title":"Limit"}},"type":"object","required":["items","total","page","limit"],"title":"FeaturedAuditLogResponse","description":"Paginated audit log response"},"FeedbackChainStats":{"properties":{"chain_id":{"type":"integer","title":"Chain Id"},"chain_name":{"type":"string","title":"Chain Name"},"total_feedbacks":{"type":"integer","title":"Total Feedbacks","default":0},"active_feedbacks":{"type":"integer","title":"Active Feedbacks","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"}},"type":"object","required":["chain_id","chain_name"],"title":"FeedbackChainStats","description":"Per-chain feedback statistics"},"FeedbackDailyTrend":{"properties":{"date":{"type":"string","format":"date","title":"Date"},"total":{"type":"integer","title":"Total","description":"Total feedbacks on this date","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"}},"type":"object","required":["date"],"title":"FeedbackDailyTrend","description":"Daily feedback trend data point"},"FeedbackDetail":{"properties":{"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Score","description":"Normalized explicit rating (0-100). Null for non-rating feedback."},"value":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Value","description":"v2.0: Feedback value (BigDecimal). Can be negative."},"value_decimals":{"anyOf":[{"type":"integer","maximum":18.0,"minimum":0.0},{"type":"null"}],"title":"Value Decimals","description":"v2.0: Original decimal places (0-18)."},"comment":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Comment","description":"Optional comment"},"feedback_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feedback Uri","description":"URI to offchain FeedbackFile (ipfs://, ar://, https://)"},"id":{"type":"string","format":"uuid","title":"Id"},"chain_id":{"type":"integer","title":"Chain Id"},"is_testnet":{"type":"boolean","title":"Is Testnet","description":"Whether this feedback is on a testnet (true) or mainnet (false) chain","default":true},"feedback_id":{"type":"string","title":"Feedback Id"},"transaction_hash":{"type":"string","title":"Transaction Hash"},"block_number":{"type":"integer","title":"Block Number","description":"Block number of the transaction"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id"},"user_address":{"type":"string","title":"User Address"},"agent":{"$ref":"#/components/schemas/app__schemas__feedback__AgentSummary","description":"Agent summary for URL construction"},"user":{"anyOf":[{"$ref":"#/components/schemas/UserSummary"},{"type":"null"}],"description":"User summary (if registered)"},"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint","description":"Agent endpoint URL at time of feedback"},"tag1":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tag1","description":"Tag1 text"},"tag2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tag2","description":"Tag2 text"},"feedback_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Feedback Index","description":"Feedback index within agent-client pair"},"feedback_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feedback Hash","description":"KECCAK-256 hash of feedback content"},"offchain_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Offchain Data","description":"Complete FeedbackFile from IPFS/HTTP"},"parse_status":{"anyOf":[{"$ref":"#/components/schemas/FeedbackParseStatus"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Parse Status","description":"Unified parse status with errors, warnings, and info"},"is_revoked":{"type":"boolean","title":"Is Revoked"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At"},"submitted_at":{"type":"string","format":"date-time","title":"Submitted At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"replies":{"anyOf":[{"$ref":"#/components/schemas/EmbeddedReplies"},{"type":"null"}],"description":"Embedded replies (up to 10). Use /feedbacks/{id}/replies if has_more=true"}},"type":"object","required":["agent_id","id","chain_id","feedback_id","transaction_hash","block_number","user_id","user_address","agent","is_revoked","revoked_at","submitted_at","created_at","updated_at"],"title":"FeedbackDetail","description":"Schema for feedback detail response (ERC-8004 v1.0 / v2.0).\n\nIncludes:\n- endpoint: Agent endpoint at time of feedback (v1.0)\n- Tags (tag1, tag2) as strings\n- Offchain data (complete FeedbackFile from IPFS/HTTP)\n- Feedback identification (feedback_index, feedback_hash)\n\nv2.0 Changes:\n- score is the normalized explicit rating (0-100) when available\n- value (BigDecimal) replaces score in v2.0\n- value_decimals stores original decimals (0-18)"},"FeedbackListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/FeedbackDetail"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"FeedbackListResponse","description":"Schema for paginated feedback list"},"FeedbackParseStatus":{"properties":{"status":{"type":"string","title":"Status","description":"Overall status: success, warning, error","default":"success"},"errors":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Errors","description":"List of parse errors"},"warnings":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Warnings","description":"List of parse warnings"},"info":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Info","description":"Info messages"},"last_parsed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Parsed At","description":"When parsing was performed"}},"type":"object","title":"FeedbackParseStatus","description":"Unified parse status for Feedback - stored in parse_status JSONB column\n\nStructure matches Agent.parse_status but without LLM fields:\n- status: Overall status (success, warning, error)\n- errors: List of error details\n- warnings: List of warning details\n- info: List of info messages\n- last_parsed_at: When parsing was last performed"},"FeedbackReply":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"feedback_id":{"type":"string","format":"uuid","title":"Feedback Id"},"chain_id":{"type":"integer","title":"Chain Id"},"responder_address":{"type":"string","title":"Responder Address","description":"Wallet address that appended this response"},"response_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Uri","description":"URI to response file (ipfs://, https://)"},"response_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Hash","description":"KECCAK-256 hash of response content"},"offchain_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Offchain Data","description":"Parsed response file content"},"offchain_fetch_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offchain Fetch Status","description":"Fetch status: pending, success, failed, no_uri"},"transaction_hash":{"type":"string","title":"Transaction Hash","description":"Transaction hash of appendResponse call"},"block_number":{"type":"integer","title":"Block Number","description":"Block number when response was appended"},"responded_at":{"type":"string","format":"date-time","title":"Responded At","description":"When the response was submitted on-chain"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","feedback_id","chain_id","responder_address","transaction_hash","block_number","responded_at","created_at","updated_at"],"title":"FeedbackReply","description":"Schema for a reply appended to feedback (ERC-8004 appendResponse).\n\nERC-8004 appendResponse allows anyone to reply to feedback:\n- Agent owner can respond with refund proof\n- Third parties can tag feedback as spam\n- Multiple replies per feedback are allowed"},"FeedbackReplyListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/FeedbackReply"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"FeedbackReplyListResponse","description":"Schema for paginated feedback reply list"},"FeedbackScoreDistribution":{"properties":{"range_0_20":{"type":"integer","title":"Range 0 20","description":"Count of feedbacks with score 0-20","default":0},"range_21_40":{"type":"integer","title":"Range 21 40","description":"Count of feedbacks with score 21-40","default":0},"range_41_60":{"type":"integer","title":"Range 41 60","description":"Count of feedbacks with score 41-60","default":0},"range_61_80":{"type":"integer","title":"Range 61 80","description":"Count of feedbacks with score 61-80","default":0},"range_81_100":{"type":"integer","title":"Range 81 100","description":"Count of feedbacks with score 81-100","default":0}},"type":"object","title":"FeedbackScoreDistribution","description":"Score distribution for feedbacks"},"FeedbackStatsResponse":{"properties":{"total_feedbacks":{"type":"integer","title":"Total Feedbacks","description":"Total number of feedbacks","default":0},"active_feedbacks":{"type":"integer","title":"Active Feedbacks","description":"Non-revoked feedbacks","default":0},"revoked_feedbacks":{"type":"integer","title":"Revoked Feedbacks","description":"Revoked feedbacks","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score","description":"Average feedback score (0-100)"},"min_score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min Score","description":"Minimum score"},"max_score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Score","description":"Maximum score"},"median_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Score","description":"Median score"},"score_distribution":{"$ref":"#/components/schemas/FeedbackScoreDistribution","description":"Score distribution by range"},"unique_users":{"type":"integer","title":"Unique Users","description":"Unique users who gave feedback","default":0},"unique_agents":{"type":"integer","title":"Unique Agents","description":"Unique agents that received feedback","default":0},"average_feedbacks_per_agent":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Feedbacks Per Agent","description":"Average feedbacks per agent"},"chain_stats":{"items":{"$ref":"#/components/schemas/FeedbackChainStats"},"type":"array","title":"Chain Stats","description":"Per-chain statistics"},"top_tags":{"items":{"$ref":"#/components/schemas/FeedbackTagStats"},"type":"array","title":"Top Tags","description":"Most used tags (top 10)"},"daily_trends":{"items":{"$ref":"#/components/schemas/FeedbackDailyTrend"},"type":"array","title":"Daily Trends","description":"Daily feedback trends (last 30 days)"},"daily_new_feedbacks":{"type":"integer","title":"Daily New Feedbacks","description":"New feedbacks in last 24h","default":0},"daily_revoked":{"type":"integer","title":"Daily Revoked","description":"Revoked feedbacks in last 24h","default":0}},"type":"object","title":"FeedbackStatsResponse","description":"Comprehensive feedback statistics response"},"FeedbackTagItem":{"properties":{"tag":{"type":"string","title":"Tag","description":"Tag value"},"count":{"type":"integer","title":"Count","description":"Number of feedbacks with this tag"},"field":{"type":"string","title":"Field","description":"Tag field: tag1 or tag2"}},"type":"object","required":["tag","count","field"],"title":"FeedbackTagItem","description":"Feedback tag with usage count"},"FeedbackTagStats":{"properties":{"tag":{"type":"string","title":"Tag"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["tag","count"],"title":"FeedbackTagStats","description":"Tag usage statistics"},"FeedbackTagsResponse":{"properties":{"tag1_values":{"items":{"$ref":"#/components/schemas/FeedbackTagItem"},"type":"array","title":"Tag1 Values","description":"Distinct tag1 values with counts"},"tag2_values":{"items":{"$ref":"#/components/schemas/FeedbackTagItem"},"type":"array","title":"Tag2 Values","description":"Distinct tag2 values with counts"},"all_tags":{"items":{"$ref":"#/components/schemas/FeedbackTagItem"},"type":"array","title":"All Tags","description":"All tags combined (sorted by count)"},"total_feedbacks_with_tags":{"type":"integer","title":"Total Feedbacks With Tags","description":"Total feedbacks with at least one tag","default":0},"total_unique_tag1":{"type":"integer","title":"Total Unique Tag1","description":"Total unique tag1 values","default":0},"total_unique_tag2":{"type":"integer","title":"Total Unique Tag2","description":"Total unique tag2 values","default":0}},"type":"object","title":"FeedbackTagsResponse","description":"Response for feedback tags listing"},"FieldSourcesData":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Source: hardcoded|onchain|offchain"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Source: hardcoded|onchain|offchain"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image","description":"Source: hardcoded|onchain|offchain"},"agent_wallet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Wallet","description":"Source: hardcoded|onchain|offchain"},"agent_wallet_chain_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Wallet Chain Id","description":"Source: hardcoded|onchain|offchain"},"x402_supported":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X402 Supported","description":"Source: hardcoded|onchain|offchain"},"mcp_server":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mcp Server","description":"Source: hardcoded|onchain|offchain"},"a2a_endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"A2A Endpoint","description":"Source: hardcoded|onchain|offchain"},"tags":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tags","description":"Source: hardcoded|onchain|offchain"},"categories":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Categories","description":"Source: hardcoded|onchain|offchain"},"capabilities":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Capabilities","description":"Source: hardcoded|onchain|offchain"}},"additionalProperties":true,"type":"object","title":"FieldSourcesData","description":"Field sources tracking - indicates where each merged field's value came from.\n\nERC-8004 agent metadata can come from three layers with different priorities:\n1. hardcoded (highest): Contract state fields (e.g., owner, agentWallet from events)\n2. onchain: Metadata set via setMetadata() transactions\n3. offchain (lowest): Metadata from agentURI (IPFS/HTTP JSON)\n\nWhen the same field exists in multiple layers, higher priority wins.\nThis data structure allows frontends to show data provenance."},"FollowResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"},"follower_count":{"type":"integer","title":"Follower Count","description":"Updated follower count of target user"},"following_count":{"type":"integer","title":"Following Count","description":"Updated following count of current user"}},"type":"object","required":["success","message","follower_count","following_count"],"title":"FollowResponse","description":"Schema for follow/unfollow operation response"},"FollowStatusResponse":{"properties":{"is_following":{"type":"boolean","title":"Is Following","description":"Whether current user follows target user"},"is_followed_by":{"type":"boolean","title":"Is Followed By","description":"Whether target user follows current user"}},"type":"object","required":["is_following","is_followed_by"],"title":"FollowStatusResponse","description":"Schema for checking follow status"},"FollowerListItem":{"properties":{"id":{"type":"string","title":"Id"},"address":{"type":"string","title":"Address","description":"Primary wallet address"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"bio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bio"},"is_verified":{"type":"boolean","title":"Is Verified","default":false},"is_official_validator":{"type":"boolean","title":"Is Official Validator","default":false},"follower_count":{"type":"integer","title":"Follower Count","default":0},"following_count":{"type":"integer","title":"Following Count","default":0},"is_following":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Following","description":"Whether current user follows this user (null if not authenticated)"},"followed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Followed At","description":"When the follow relationship was created"}},"type":"object","required":["id","address"],"title":"FollowerListItem","description":"Schema for a user in followers/following list"},"FollowerListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/FollowerListItem"},"type":"array","title":"Data"},"total":{"type":"integer","title":"Total","description":"Total number of followers/following"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["data","total","limit","offset"],"title":"FollowerListResponse","description":"Schema for paginated followers/following list"},"FreshnessComponentStatus":{"properties":{"name":{"type":"string","title":"Name"},"status":{"type":"string","enum":["ok","degraded","down","unknown"],"title":"Status"},"total":{"type":"integer","title":"Total"},"stale_warning":{"type":"integer","title":"Stale Warning"},"stale_critical":{"type":"integer","title":"Stale Critical"},"warning_after_seconds":{"type":"integer","title":"Warning After Seconds"},"critical_after_seconds":{"type":"integer","title":"Critical After Seconds"},"newest_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Newest At"},"age_p50_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Age P50 Seconds"},"age_p95_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Age P95 Seconds"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["name","status","total","stale_warning","stale_critical","warning_after_seconds","critical_after_seconds"],"title":"FreshnessComponentStatus"},"FreshnessStatusResponse":{"properties":{"status":{"type":"string","enum":["ok","degraded","down","unknown"],"title":"Status"},"checked_at":{"type":"string","format":"date-time","title":"Checked At"},"components":{"items":{"$ref":"#/components/schemas/FreshnessComponentStatus"},"type":"array","title":"Components"}},"type":"object","required":["status","checked_at","components"],"title":"FreshnessStatusResponse"},"GlobalStatsResponse":{"properties":{"total_agents":{"type":"integer","title":"Total Agents","description":"Total number of agents","default":0},"total_users":{"type":"integer","title":"Total Users","description":"Total number of users","default":0},"total_validators":{"type":"integer","title":"Total Validators","description":"Total number of validators","default":0},"total_feedbacks":{"type":"integer","title":"Total Feedbacks","description":"Total number of feedbacks","default":0},"total_validations":{"type":"integer","title":"Total Validations","description":"Total number of validations","default":0},"total_chats":{"type":"integer","title":"Total Chats","description":"Total number of chats","default":0},"total_messages":{"type":"integer","title":"Total Messages","description":"Total number of messages","default":0},"daily_new_agents":{"type":"integer","title":"Daily New Agents","description":"New agents in last 24h","default":0},"daily_new_users":{"type":"integer","title":"Daily New Users","description":"New users in last 24h","default":0},"daily_feedbacks":{"type":"integer","title":"Daily Feedbacks","description":"Feedbacks in last 24h","default":0},"daily_validations":{"type":"integer","title":"Daily Validations","description":"Validations in last 24h","default":0},"average_feedback_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Feedback Score","description":"Average feedback score"},"average_validation_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Validation Score","description":"Average validation score"},"supported_chains":{"items":{"$ref":"#/components/schemas/SupportedChainInfo"},"type":"array","title":"Supported Chains","description":"List of all supported chains with their info"},"chain_stats":{"items":{"$ref":"#/components/schemas/ChainDetailedStats"},"type":"array","title":"Chain Stats","description":"Detailed statistics for each chain"},"protocol_distribution":{"additionalProperties":{"type":"integer"},"type":"object","title":"Protocol Distribution","description":"Agent count by protocol"},"registration_stats":{"additionalProperties":{"type":"integer"},"type":"object","title":"Registration Stats","description":"Multi-chain registration statistics: total, resolved, unresolved, owner_verified, reciprocal_verified"}},"type":"object","title":"GlobalStatsResponse","description":"Schema for global platform statistics (real-time)"},"GrowthAnalysisResponse":{"properties":{"metric":{"type":"string","title":"Metric","description":"Metric name (agents, users, feedbacks, validations)"},"period":{"type":"string","title":"Period","description":"Analysis period (7d, 30d, 90d, all)"},"data":{"items":{"$ref":"#/components/schemas/GrowthDataPoint"},"type":"array","title":"Data"},"total_growth":{"type":"integer","title":"Total Growth","description":"Total growth in period"},"average_growth_rate":{"type":"number","title":"Average Growth Rate","description":"Average growth rate (%)"},"current_value":{"type":"integer","title":"Current Value","description":"Current total value"}},"type":"object","required":["metric","period","data","total_growth","average_growth_rate","current_value"],"title":"GrowthAnalysisResponse","description":"Schema for growth trend analysis"},"GrowthDataPoint":{"properties":{"date":{"type":"string","format":"date","title":"Date"},"value":{"type":"integer","title":"Value"},"growth_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Growth Rate","description":"Growth rate vs previous period (%)"}},"type":"object","required":["date","value"],"title":"GrowthDataPoint","description":"Schema for a single growth data point"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IPFSFetchResponse":{"properties":{"cid":{"type":"string","title":"Cid","description":"IPFS Content Identifier"},"content":{"additionalProperties":true,"type":"object","title":"Content","description":"Retrieved JSON content"}},"type":"object","required":["cid","content"],"title":"IPFSFetchResponse","description":"Schema for IPFS fetch response"},"IPFSUploadRequest":{"properties":{"content":{"additionalProperties":true,"type":"object","title":"Content","description":"JSON content to upload to IPFS"}},"type":"object","required":["content"],"title":"IPFSUploadRequest","description":"Schema for IPFS upload request"},"IPFSUploadResponse":{"properties":{"cid":{"type":"string","title":"Cid","description":"IPFS Content Identifier (CID)"},"uri":{"type":"string","title":"Uri","description":"IPFS URI (ipfs://{cid})"},"gateway_url":{"type":"string","title":"Gateway Url","description":"Public gateway URL for accessing content"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Additional notes (e.g., for mock data)"}},"type":"object","required":["cid","uri","gateway_url"],"title":"IPFSUploadResponse","description":"Schema for IPFS upload response"},"InboxListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/InboxMessageResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"unread_count":{"type":"integer","title":"Unread Count"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","unread_count","limit","offset"],"title":"InboxListResponse","description":"Schema for paginated inbox list"},"InboxMessageResponse":{"properties":{"id":{"type":"string","title":"Id"},"type":{"$ref":"#/components/schemas/MessageType"},"title":{"type":"string","title":"Title"},"content":{"type":"string","title":"Content"},"related_agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Related Agent Id"},"related_feedback_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Related Feedback Id"},"related_validation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Related Validation Id"},"agent_preview":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Agent Preview","description":"Agent preview: {chain_id, token_id, name}"},"meta":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Meta"},"is_read":{"type":"boolean","title":"Is Read"},"read_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Read At"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","type","title","content","is_read","created_at"],"title":"InboxMessageResponse","description":"Schema for inbox message response"},"IndexerStatusItem":{"properties":{"chain_key":{"type":"string","title":"Chain Key"},"chain_id":{"type":"integer","title":"Chain Id"},"chain_name":{"type":"string","title":"Chain Name"},"chain_type":{"type":"string","title":"Chain Type"},"data_source":{"type":"string","title":"Data Source"},"status":{"type":"string","enum":["ok","degraded","down","unknown"],"title":"Status"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"cursor_age_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cursor Age Seconds"},"last_cursor_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Cursor At"},"checkpoint_age_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Checkpoint Age Seconds"},"checkpoint_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checkpoint Status"},"last_checkpoint_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Checkpoint At"},"warn_after_seconds":{"type":"integer","title":"Warn After Seconds"},"down_after_seconds":{"type":"integer","title":"Down After Seconds"},"direct_rpc_configured":{"type":"boolean","title":"Direct Rpc Configured","default":false},"direct_rpc_status":{"anyOf":[{"type":"string","enum":["ok","degraded","down","unknown"]},{"type":"null"}],"title":"Direct Rpc Status"},"direct_rpc_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direct Rpc Message"},"direct_rpc_required":{"type":"boolean","title":"Direct Rpc Required","default":false},"direct_canonical_checkpoint_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Direct Canonical Checkpoint Block"},"direct_canonical_checkpoint_age_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Direct Canonical Checkpoint Age Seconds"},"direct_canonical_checkpoint_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direct Canonical Checkpoint Status"},"direct_canonical_last_checkpoint_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Direct Canonical Last Checkpoint At"},"direct_shadow_checkpoint_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Direct Shadow Checkpoint Block"},"direct_shadow_checkpoint_age_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Direct Shadow Checkpoint Age Seconds"},"direct_pending_events":{"type":"integer","title":"Direct Pending Events","default":0},"direct_failed_events":{"type":"integer","title":"Direct Failed Events","default":0},"direct_reorged_events":{"type":"integer","title":"Direct Reorged Events","default":0},"direct_latest_event_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Direct Latest Event Block"},"direct_latest_event_block_age_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Direct Latest Event Block Age Seconds"},"direct_latest_processed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Direct Latest Processed At"}},"type":"object","required":["chain_key","chain_id","chain_name","chain_type","data_source","status","warn_after_seconds","down_after_seconds"],"title":"IndexerStatusItem"},"IndexersStatusResponse":{"properties":{"status":{"type":"string","enum":["ok","degraded","down","unknown"],"title":"Status"},"checked_at":{"type":"string","format":"date-time","title":"Checked At"},"event_status_count_cap":{"type":"integer","title":"Event Status Count Cap"},"indexers":{"items":{"$ref":"#/components/schemas/IndexerStatusItem"},"type":"array","title":"Indexers"}},"type":"object","required":["status","checked_at","event_status_count_cap","indexers"],"title":"IndexersStatusResponse"},"IsStarredResponse":{"properties":{"agent_id":{"type":"string","title":"Agent Id"},"user_id":{"type":"string","title":"User Id"},"is_starred":{"type":"boolean","title":"Is Starred"}},"type":"object","required":["agent_id","user_id","is_starred"],"title":"IsStarredResponse","description":"Schema for checking if agent is starred"},"LeaderboardShadowMethodInfo":{"properties":{"name":{"type":"string","title":"Name"},"primary_order":{"items":{"type":"string"},"type":"array","title":"Primary Order"},"evidence_tiers":{"additionalProperties":{"type":"string"},"type":"object","title":"Evidence Tiers"},"integrity_tiers":{"additionalProperties":{"type":"string"},"type":"object","title":"Integrity Tiers"}},"type":"object","required":["name","primary_order","evidence_tiers","integrity_tiers"],"title":"LeaderboardShadowMethodInfo","description":"Metadata describing the shadow-ranking method."},"LeaderboardShadowReviewItem":{"properties":{"current_rank":{"type":"integer","title":"Current Rank"},"shadow_rank":{"type":"integer","title":"Shadow Rank"},"delta":{"type":"integer","title":"Delta"},"chain_id":{"type":"integer","title":"Chain Id"},"token_id":{"type":"string","title":"Token Id"},"name":{"type":"string","title":"Name"},"total_score":{"type":"number","title":"Total Score"},"feedbacks":{"type":"integer","title":"Feedbacks"},"average_score":{"type":"number","title":"Average Score"},"stars":{"type":"integer","title":"Stars"},"health_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Health Score"},"evidence_tier":{"type":"string","title":"Evidence Tier"},"integrity_tier":{"type":"string","title":"Integrity Tier"},"discoverability_tier":{"type":"string","title":"Discoverability Tier"},"merit_score":{"type":"number","title":"Merit Score"},"proof_score":{"type":"number","title":"Proof Score"},"support_score":{"type":"number","title":"Support Score"},"feedback_volume_score":{"type":"number","title":"Feedback Volume Score"},"reach_score":{"type":"number","title":"Reach Score"},"trust_score":{"type":"number","title":"Trust Score"},"service_score":{"type":"number","title":"Service Score"},"publisher_score":{"type":"number","title":"Publisher Score"},"compliance_score":{"type":"number","title":"Compliance Score"},"review_priority":{"type":"string","title":"Review Priority"},"review_tags":{"items":{"type":"string"},"type":"array","title":"Review Tags"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes"}},"type":"object","required":["current_rank","shadow_rank","delta","chain_id","token_id","name","total_score","feedbacks","average_score","stars","health_score","evidence_tier","integrity_tier","discoverability_tier","merit_score","proof_score","support_score","feedback_volume_score","reach_score","trust_score","service_score","publisher_score","compliance_score","review_priority","review_tags","notes"],"title":"LeaderboardShadowReviewItem","description":"Single row in shadow leaderboard review output."},"LeaderboardShadowReviewResponse":{"properties":{"generated_at":{"type":"string","format":"date-time","title":"Generated At"},"limit":{"type":"integer","title":"Limit"},"show_top":{"type":"integer","title":"Show Top"},"total_analyzed":{"type":"integer","title":"Total Analyzed"},"filtered_rows_count":{"type":"integer","title":"Filtered Rows Count"},"is_testnet":{"type":"boolean","title":"Is Testnet"},"chain_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chain Id"},"filters_applied":{"additionalProperties":true,"type":"object","title":"Filters Applied"},"method":{"$ref":"#/components/schemas/LeaderboardShadowMethodInfo"},"top_rows":{"items":{"$ref":"#/components/schemas/LeaderboardShadowReviewItem"},"type":"array","title":"Top Rows"},"summary":{"$ref":"#/components/schemas/LeaderboardShadowSummary"}},"type":"object","required":["generated_at","limit","show_top","total_analyzed","filtered_rows_count","is_testnet","chain_id","filters_applied","method","top_rows","summary"],"title":"LeaderboardShadowReviewResponse","description":"Shadow leaderboard review response for admin UI."},"LeaderboardShadowSummary":{"properties":{"band_counts_top_n":{"additionalProperties":{"type":"integer"},"type":"object","title":"Band Counts Top N"},"biggest_drops":{"items":{"$ref":"#/components/schemas/LeaderboardShadowReviewItem"},"type":"array","title":"Biggest Drops"},"biggest_rises":{"items":{"$ref":"#/components/schemas/LeaderboardShadowReviewItem"},"type":"array","title":"Biggest Rises"},"suspicious_current_top_n":{"items":{"$ref":"#/components/schemas/LeaderboardShadowReviewItem"},"type":"array","title":"Suspicious Current Top N"}},"type":"object","required":["band_counts_top_n","biggest_drops","biggest_rises","suspicious_current_top_n"],"title":"LeaderboardShadowSummary","description":"Summary buckets for admin review."},"LoginResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","description":"JWT access token"},"refresh_token":{"type":"string","title":"Refresh Token","description":"JWT refresh token"},"token_type":{"type":"string","title":"Token Type","description":"Token type","default":"bearer"},"expires_in":{"type":"integer","title":"Expires In","description":"Access token expiration in seconds"},"user_id":{"type":"string","title":"User Id","description":"User ID"},"wallet_address":{"type":"string","title":"Wallet Address","description":"Primary wallet address"},"is_new_user":{"type":"boolean","title":"Is New User","description":"Whether this is a newly created user","default":false}},"type":"object","required":["access_token","refresh_token","expires_in","user_id","wallet_address"],"title":"LoginResponse","description":"Schema for login response"},"LogoutResponse":{"properties":{"message":{"type":"string","title":"Message","default":"Successfully logged out"}},"type":"object","title":"LogoutResponse","description":"Schema for logout response"},"MCPAgentDetail":{"properties":{"chain_id":{"type":"integer","title":"Chain Id"},"token_id":{"type":"integer","title":"Token Id"},"registry_address":{"type":"string","title":"Registry Address"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"},"total_score":{"type":"number","title":"Total Score"},"total_stars":{"type":"integer","title":"Total Stars"},"total_feedbacks":{"type":"integer","title":"Total Feedbacks"},"owner_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Address"},"agent_wallet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Wallet"},"endpoints":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Endpoints"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"oasf_skills":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Oasf Skills"},"oasf_domains":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Oasf Domains"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"network_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Network Rank"}},"type":"object","required":["chain_id","token_id","registry_address","name","description","image_url","total_score","total_stars","total_feedbacks","owner_address","agent_wallet","endpoints","metadata","oasf_skills","oasf_domains","created_at"],"title":"MCPAgentDetail","description":"Detailed agent information for MCP"},"MCPAgentSummary":{"properties":{"chain_id":{"type":"integer","title":"Chain Id"},"token_id":{"type":"integer","title":"Token Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"},"total_score":{"type":"number","title":"Total Score"},"total_stars":{"type":"integer","title":"Total Stars"},"total_feedbacks":{"type":"integer","title":"Total Feedbacks"},"owner_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Address"},"agent_wallet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Wallet"}},"type":"object","required":["chain_id","token_id","name","description","image_url","total_score","total_stars","total_feedbacks","owner_address","agent_wallet"],"title":"MCPAgentSummary","description":"Simplified agent summary for MCP responses"},"MCPEndpoint":{"properties":{"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version"},"tools":{"items":{"type":"string"},"type":"array","title":"Tools"},"prompts":{"items":{"type":"string"},"type":"array","title":"Prompts"},"resources":{"items":{"type":"string"},"type":"array","title":"Resources"}},"type":"object","title":"MCPEndpoint","description":"MCP endpoint details"},"MCPFeedbackItem":{"properties":{"feedback_id":{"type":"string","title":"Feedback Id"},"chain_id":{"type":"integer","title":"Chain Id"},"score":{"type":"integer","title":"Score"},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment"},"user_address":{"type":"string","title":"User Address"},"submitted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitted At"},"tag1":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tag1"},"tag2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tag2"}},"type":"object","required":["feedback_id","chain_id","score","comment","user_address","submitted_at","tag1","tag2"],"title":"MCPFeedbackItem","description":"Feedback item for MCP"},"MCPFeedbackResponse":{"properties":{"count":{"type":"integer","title":"Count"},"feedbacks":{"items":{"$ref":"#/components/schemas/MCPFeedbackItem"},"type":"array","title":"Feedbacks"}},"type":"object","required":["count","feedbacks"],"title":"MCPFeedbackResponse","description":"Feedback list response"},"MCPSearchResponse":{"properties":{"count":{"type":"integer","title":"Count"},"agents":{"items":{"$ref":"#/components/schemas/MCPSearchResult"},"type":"array","title":"Agents"}},"type":"object","required":["count","agents"],"title":"MCPSearchResponse","description":"Search response"},"MCPSearchResult":{"properties":{"chain_id":{"type":"integer","title":"Chain Id"},"token_id":{"type":"integer","title":"Token Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"},"total_score":{"type":"number","title":"Total Score"},"similarity_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Similarity Score"}},"type":"object","required":["chain_id","token_id","name","description","image_url","total_score"],"title":"MCPSearchResult","description":"Search result with similarity score"},"MCPStarResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"},"star_count":{"type":"integer","title":"Star Count"}},"type":"object","required":["success","message","star_count"],"title":"MCPStarResponse","description":"Star/unstar response"},"MCPStarredAgentsResponse":{"properties":{"count":{"type":"integer","title":"Count"},"agents":{"items":{"$ref":"#/components/schemas/MCPAgentSummary"},"type":"array","title":"Agents"}},"type":"object","required":["count","agents"],"title":"MCPStarredAgentsResponse","description":"Starred agents list response"},"MarkReadRequest":{"properties":{"message_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Message Ids","description":"Specific message IDs to mark as read. If None, marks all as read."}},"type":"object","title":"MarkReadRequest","description":"Schema for marking messages as read"},"MarkReadResponse":{"properties":{"marked_count":{"type":"integer","title":"Marked Count"}},"type":"object","required":["marked_count"],"title":"MarkReadResponse","description":"Schema for mark read result"},"MessageType":{"type":"string","enum":["feedback.received","feedback.revoked","validation.requested","validation.completed","star.received","star.removed","watch.received","watch.removed","agent.updated","follow.new","follow.lost","system.announcement","welcome"],"title":"MessageType","description":"Inbox message types"},"MostPopularAgent":{"properties":{"chain_id":{"type":"integer","title":"Chain Id"},"token_id":{"type":"integer","title":"Token Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"type":"object","required":["chain_id","token_id"],"title":"MostPopularAgent","description":"Most popular agent summary"},"NonceRequest":{"properties":{"wallet_address":{"type":"string","maxLength":44,"minLength":32,"title":"Wallet Address"}},"type":"object","required":["wallet_address"],"title":"NonceRequest","description":"Schema for requesting a login nonce"},"NonceResponse":{"properties":{"nonce":{"type":"string","title":"Nonce","description":"Random nonce for signing"},"message":{"type":"string","title":"Message","description":"Message to be signed by the wallet"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Nonce expiration time"}},"type":"object","required":["nonce","message","expires_at"],"title":"NonceResponse","description":"Schema for nonce response"},"NotificationSettingsResponse":{"properties":{"inbox":{"$ref":"#/components/schemas/ChannelSettings"},"webhook":{"$ref":"#/components/schemas/ChannelSettings"}},"type":"object","title":"NotificationSettingsResponse","description":"Full notification settings response"},"NotificationSettingsUpdate":{"properties":{"inbox":{"anyOf":[{"$ref":"#/components/schemas/ChannelSettings"},{"type":"null"}]},"webhook":{"anyOf":[{"$ref":"#/components/schemas/ChannelSettings"},{"type":"null"}]}},"type":"object","title":"NotificationSettingsUpdate","description":"Schema for updating notification settings"},"OASFDomainUsageItem":{"properties":{"domain":{"type":"string","title":"Domain","description":"Domain value"},"count":{"type":"integer","title":"Count","description":"Number of agents using this domain"},"is_standard":{"type":"boolean","title":"Is Standard","description":"Whether this is a standard OASF domain category","default":false},"category_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Category Id","description":"Standard category ID if is_standard=True"}},"type":"object","required":["domain","count"],"title":"OASFDomainUsageItem","description":"OASF domain usage statistics"},"OASFDomainsResponse":{"properties":{"used_domains":{"items":{"$ref":"#/components/schemas/OASFDomainUsageItem"},"type":"array","title":"Used Domains","description":"Domains used by agents (sorted by count)"},"total_agents_with_oasf":{"type":"integer","title":"Total Agents With Oasf","description":"Total agents with OASF endpoint","default":0},"total_unique_domains":{"type":"integer","title":"Total Unique Domains","description":"Total unique domain values","default":0}},"type":"object","title":"OASFDomainsResponse","description":"Response for OASF domains listing"},"OASFEndpoint":{"properties":{"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version"},"skills":{"items":{"type":"string"},"type":"array","title":"Skills"},"domains":{"items":{"type":"string"},"type":"array","title":"Domains"}},"type":"object","title":"OASFEndpoint","description":"OASF endpoint details"},"OASFSkillUsageItem":{"properties":{"skill":{"type":"string","title":"Skill","description":"Skill value (name or ID)"},"count":{"type":"integer","title":"Count","description":"Number of agents using this skill"},"is_standard":{"type":"boolean","title":"Is Standard","description":"Whether this is a standard OASF category","default":false},"category_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Category Id","description":"Standard category ID if is_standard=True"}},"type":"object","required":["skill","count"],"title":"OASFSkillUsageItem","description":"OASF skill usage statistics"},"OASFSkillsResponse":{"properties":{"used_skills":{"items":{"$ref":"#/components/schemas/OASFSkillUsageItem"},"type":"array","title":"Used Skills","description":"Skills used by agents (sorted by count)"},"total_agents_with_oasf":{"type":"integer","title":"Total Agents With Oasf","description":"Total agents with OASF endpoint","default":0},"total_unique_skills":{"type":"integer","title":"Total Unique Skills","description":"Total unique skill values","default":0}},"type":"object","title":"OASFSkillsResponse","description":"Response for OASF skills listing"},"OnchainMetadataItem":{"properties":{"key":{"type":"string","title":"Key"},"value":{"type":"string","title":"Value"},"decoded":{"title":"Decoded"}},"type":"object","required":["key","value"],"title":"OnchainMetadataItem","description":"Single on-chain metadata key-value pair"},"OwnerHealthCheckRequestResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Status message"},"queued":{"type":"boolean","title":"Queued","description":"Whether the health check was queued","default":true},"task_id":{"type":"string","title":"Task Id","description":"Celery task ID"},"daily_limit":{"type":"integer","minimum":0.0,"title":"Daily Limit","description":"Daily request limit for this owner/agent"},"remaining_today":{"type":"integer","minimum":0.0,"title":"Remaining Today","description":"Accepted requests remaining today"},"reset_at":{"type":"string","format":"date-time","title":"Reset At","description":"UTC time when the daily limit resets"},"cooldown_seconds":{"type":"integer","minimum":0.0,"title":"Cooldown Seconds","description":"Cooldown after an accepted request"},"next_allowed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Allowed At","description":"Next time this owner can request another check for this agent"},"last_health_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Health Checked At","description":"Last persisted health check timestamp before this request"},"estimated_health_check_at":{"type":"string","format":"date-time","title":"Estimated Health Check At","description":"Estimated time when the queued health check may start"},"estimated_score_refresh_window_seconds":{"type":"integer","minimum":0.0,"title":"Estimated Score Refresh Window Seconds","description":"Estimated score refresh window after health check completion"},"next_ranking_refresh_at":{"type":"string","format":"date-time","title":"Next Ranking Refresh At","description":"Next scheduled scoring/ranking refresh time"},"ranking_refresh_interval_minutes":{"type":"integer","minimum":1.0,"title":"Ranking Refresh Interval Minutes","description":"Configured scoring/ranking refresh interval"}},"type":"object","required":["message","task_id","daily_limit","remaining_today","reset_at","cooldown_seconds","estimated_health_check_at","estimated_score_refresh_window_seconds","next_ranking_refresh_at","ranking_refresh_interval_minutes"],"title":"OwnerHealthCheckRequestResponse","description":"Response after an owner requests an agent health check."},"OwnerMetadataRefreshRequestResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Status message"},"queued":{"type":"boolean","title":"Queued","description":"Whether the metadata refresh was queued","default":true},"task_id":{"type":"string","title":"Task Id","description":"Celery task ID"},"daily_limit":{"type":"integer","minimum":0.0,"title":"Daily Limit","description":"Daily request limit for this owner/agent"},"remaining_today":{"type":"integer","minimum":0.0,"title":"Remaining Today","description":"Accepted requests remaining today"},"reset_at":{"type":"string","format":"date-time","title":"Reset At","description":"UTC time when the daily limit resets"},"cooldown_seconds":{"type":"integer","minimum":0.0,"title":"Cooldown Seconds","description":"Cooldown after an accepted request"},"next_allowed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Allowed At","description":"Next time this owner can request another refresh"},"last_metadata_refreshed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Metadata Refreshed At","description":"Last persisted metadata parse timestamp before this request"},"estimated_refresh_at":{"type":"string","format":"date-time","title":"Estimated Refresh At","description":"Estimated time when the queued refresh may start"}},"type":"object","required":["message","task_id","daily_limit","remaining_today","reset_at","cooldown_seconds","estimated_refresh_at"],"title":"OwnerMetadataRefreshRequestResponse","description":"Response after an owner requests an agent metadata refresh."},"PageViewStatsResponse":{"properties":{"agent_id":{"type":"string","title":"Agent Id","description":"Agent UUID"},"total_views":{"type":"integer","minimum":0.0,"title":"Total Views","description":"Total views all-time"},"unique_visitors":{"type":"integer","minimum":0.0,"title":"Unique Visitors","description":"Unique visitors all-time"},"views_24h":{"type":"integer","minimum":0.0,"title":"Views 24H","description":"Views in last 24 hours"},"views_7d":{"type":"integer","minimum":0.0,"title":"Views 7D","description":"Views in last 7 days"},"views_30d":{"type":"integer","minimum":0.0,"title":"Views 30D","description":"Views in last 30 days"}},"type":"object","required":["agent_id","total_views","unique_visitors","views_24h","views_7d","views_30d"],"title":"PageViewStatsResponse","description":"Page view statistics for an agent"},"PaginatedResponse":{"properties":{"items":{"items":{},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"limit":{"type":"integer","title":"Limit"}},"type":"object","required":["items","total","page","limit"],"title":"PaginatedResponse","description":"Generic paginated response"},"ParseStatusData":{"properties":{"status":{"type":"string","title":"Status","description":"Overall status: success, warning, error","default":"success"},"errors":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Errors"},"warnings":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Warnings"},"info":{"items":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"string"}]},"type":"array","title":"Info","description":"Info messages (recommendations, expected states)"},"llm_attempted":{"type":"boolean","title":"Llm Attempted","default":false},"llm_attempted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Llm Attempted At"},"last_parsed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Parsed At"}},"type":"object","title":"ParseStatusData","description":"Unified parse status - stored in parse_status JSONB column"},"PublisherCertificationAdminAssign":{"properties":{"tier":{"type":"string","pattern":"^(OFFICIAL|VERIFIED|COMMUNITY)$","title":"Tier"},"reason":{"type":"string","maxLength":1000,"minLength":5,"title":"Reason"},"contact_verified":{"type":"boolean","title":"Contact Verified","description":"Admin confirms they have communicated with the applicant and verified project ownership. Must be True to approve."},"kyc_verified":{"type":"boolean","title":"Kyc Verified","default":false},"certification_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Certification Expires At"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"}},"type":"object","required":["tier","reason","contact_verified"],"title":"PublisherCertificationAdminAssign","description":"Admin: assign publisher tier.\n\nIMPORTANT: contact_verified must be True to approve. This confirms that\nthe admin has communicated with the applicant (via email or Telegram) and\nverified their project ownership claim."},"PublisherCertificationAdminReject":{"properties":{"reason":{"type":"string","maxLength":1000,"minLength":5,"title":"Reason"}},"type":"object","required":["reason"],"title":"PublisherCertificationAdminReject","description":"Admin: reject pending publisher certification application"},"PublisherCertificationAdminRevoke":{"properties":{"reason":{"type":"string","maxLength":1000,"minLength":5,"title":"Reason"}},"type":"object","required":["reason"],"title":"PublisherCertificationAdminRevoke","description":"Admin: revoke approved publisher certification"},"PublisherCertificationCreate":{"properties":{"reason":{"type":"string","maxLength":1000,"minLength":10,"title":"Reason","description":"Why you want to publish agents and what project(s) you represent"},"organization_name":{"type":"string","maxLength":255,"minLength":2,"title":"Organization Name","description":"Your organization or project name (required)"},"project_url":{"type":"string","maxLength":500,"minLength":5,"title":"Project Url","description":"Project URL (GitHub repo, official website, or documentation site)"},"organization_website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Website","description":"Organization website (if different from project_url)"},"organization_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Email","description":"Organization contact email for verification"},"contact_telegram":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Contact Telegram","description":"Telegram handle (e.g. @username) for verification communication"},"project_contract_address":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Project Contract Address","description":"On-chain contract address related to the project (if applicable)"}},"type":"object","required":["reason","organization_name","project_url"],"title":"PublisherCertificationCreate","description":"Request to apply for publisher certification.\n\nPublisher certification requires human review. After submitting this\napplication, you MUST contact the 8004scan team via email or Telegram\nto provide additional materials proving project ownership. Applications\nwill not be approved without verified communication."},"PublisherCertificationResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"user_id":{"type":"string","format":"uuid","title":"User Id"},"tier":{"type":"string","title":"Tier"},"status":{"type":"string","title":"Status"},"certification_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Certification Reason"},"kyc_verified":{"type":"boolean","title":"Kyc Verified"},"kyc_verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Kyc Verified At"},"is_active":{"type":"boolean","title":"Is Active"},"is_expired":{"type":"boolean","title":"Is Expired"},"organization_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Name"},"organization_website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Website"},"organization_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Email"},"contact_telegram":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Telegram"},"project_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Url"},"project_contract_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Contract Address"},"contact_verified":{"type":"boolean","title":"Contact Verified"},"contact_verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Contact Verified At"},"certified_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Certified Name"},"certified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Certified At"},"certification_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Certification Expires At"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","user_id","tier","status","certification_reason","kyc_verified","kyc_verified_at","is_active","is_expired","organization_name","organization_website","organization_email","contact_telegram","project_url","project_contract_address","contact_verified","contact_verified_at","certified_at","certification_expires_at","created_at","updated_at"],"title":"PublisherCertificationResponse","description":"Publisher certification response"},"PublisherCertifiedNameUpdate":{"properties":{"certified_name":{"anyOf":[{"type":"string","maxLength":100,"minLength":2},{"type":"null"}],"title":"Certified Name","description":"Platform-assigned display name (e.g. 'Uniswap Project Team'). Set to null to clear."}},"type":"object","title":"PublisherCertifiedNameUpdate","description":"Admin: set or clear publisher certified name (platform-assigned display name)"},"PublisherLeaderboardItem":{"properties":{"rank":{"type":"integer","title":"Rank","description":"Publisher rank in leaderboard (1-based)"},"publisher_address":{"type":"string","title":"Publisher Address","description":"Publisher wallet address"},"publisher_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publisher Name","description":"Publisher display name (if set)"},"publisher_avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publisher Avatar Url","description":"Publisher avatar URL"},"total_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Total Score","description":"Composite leaderboard score (0-100)"},"agent_count":{"type":"integer","title":"Agent Count","description":"Total number of agents published","default":0},"avg_agent_quality":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Avg Agent Quality","description":"Average quality score of agents","default":0},"total_stars":{"type":"integer","title":"Total Stars","description":"Total stars across all agents","default":0},"total_watches":{"type":"integer","title":"Total Watches","description":"Total watches across all agents","default":0},"total_feedbacks":{"type":"integer","title":"Total Feedbacks","description":"Total feedbacks across all agents","default":0},"validated_agents":{"type":"integer","title":"Validated Agents","description":"Number of validated agents","default":0},"validation_rate":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Validation Rate","description":"Percentage of agents validated (0-100)","default":0},"top_agents":{"items":{"$ref":"#/components/schemas/PublisherTopAgent"},"type":"array","maxItems":3,"title":"Top Agents","description":"Top 3 agents by score"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id","description":"Associated user ID (if linked)"},"first_agent_created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Agent Created At","description":"First agent creation timestamp"},"last_agent_created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Agent Created At","description":"Most recent agent creation timestamp"}},"type":"object","required":["rank","publisher_address","total_score"],"title":"PublisherLeaderboardItem","description":"Schema for publisher leaderboard item"},"PublisherLeaderboardResponse":{"properties":{"total":{"type":"integer","title":"Total","description":"Total number of publishers matching filters"},"limit":{"type":"integer","title":"Limit","description":"Number of items per page"},"offset":{"type":"integer","title":"Offset","description":"Pagination offset"},"items":{"items":{"$ref":"#/components/schemas/PublisherLeaderboardItem"},"type":"array","title":"Items","description":"Publisher leaderboard items"}},"type":"object","required":["total","limit","offset"],"title":"PublisherLeaderboardResponse","description":"Schema for publisher leaderboard response"},"PublisherTopAgent":{"properties":{"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"Agent UUID"},"name":{"type":"string","title":"Name","description":"Agent name"},"total_score":{"type":"number","title":"Total Score","description":"Agent total score"}},"type":"object","required":["agent_id","name","total_score"],"title":"PublisherTopAgent","description":"Schema for top agent preview in publisher leaderboard"},"QualityEndpointHealthSummary":{"properties":{"overall_status":{"type":"string","enum":["healthy","degraded","unhealthy","unknown","skipped"],"title":"Overall Status","default":"unknown"},"health_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Health Score"},"checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Checked At"},"declared_services_count":{"type":"integer","minimum":0.0,"title":"Declared Services Count"},"counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Counts"},"services":{"items":{"$ref":"#/components/schemas/QualityHealthService"},"type":"array","title":"Services"}},"type":"object","required":["declared_services_count"],"title":"QualityEndpointHealthSummary"},"QualityHealthService":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"status":{"type":"string","enum":["healthy","degraded","unhealthy","unknown","skipped"],"title":"Status"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latency Ms"},"checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Checked At"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"domain_verified":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Domain Verified"},"verification_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verification Status"},"verification_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verification Error"}},"type":"object","required":["key","label","status"],"title":"QualityHealthService"},"QualityMetadataIssue":{"properties":{"severity":{"type":"string","enum":["error","warning","info"],"title":"Severity"},"code":{"type":"string","title":"Code"},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field"},"message":{"type":"string","title":"Message"},"onchain_value":{"anyOf":[{},{"type":"null"}],"title":"Onchain Value"},"offchain_value":{"anyOf":[{},{"type":"null"}],"title":"Offchain Value"}},"type":"object","required":["severity","code","message"],"title":"QualityMetadataIssue"},"QualityMetadataValidationSummary":{"properties":{"status":{"type":"string","enum":["success","warning","error","timeout","unknown"],"title":"Status"},"last_parsed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Parsed At"},"counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Counts"},"issues":{"items":{"$ref":"#/components/schemas/QualityMetadataIssue"},"type":"array","title":"Issues"}},"type":"object","required":["status"],"title":"QualityMetadataValidationSummary"},"QualityRiskFlag":{"properties":{"id":{"type":"string","title":"Id"},"severity":{"type":"string","enum":["high","medium","low"],"title":"Severity"},"category":{"type":"string","enum":["metadata","endpoint","score","reputation","wallet","service"],"title":"Category"},"title":{"type":"string","title":"Title"},"description":{"type":"string","title":"Description"},"evidence":{"additionalProperties":true,"type":"object","title":"Evidence"},"source":{"type":"string","title":"Source"},"detected_at":{"type":"string","format":"date-time","title":"Detected At"}},"type":"object","required":["id","severity","category","title","description","source","detected_at"],"title":"QualityRiskFlag"},"QualityScoreDimension":{"properties":{"key":{"type":"string","enum":["engagement","service","publisher","compliance","momentum"],"title":"Key"},"label":{"type":"string","title":"Label"},"score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Score"},"weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Weight"},"weighted_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Weighted Score"},"explanation":{"type":"string","title":"Explanation","default":""},"details":{"additionalProperties":true,"type":"object","title":"Details"}},"type":"object","required":["key","label","score","weight","weighted_score"],"title":"QualityScoreDimension"},"QualityScoreHistoryPoint":{"properties":{"scored_at":{"type":"string","format":"date-time","title":"Scored At"},"total_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Total Score"},"engagement_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Engagement Score"},"service_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Service Score"},"publisher_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Publisher Score"},"compliance_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Compliance Score"},"momentum_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Momentum Score"},"score_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Score Version"},"algorithm":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Algorithm"}},"type":"object","required":["scored_at","total_score"],"title":"QualityScoreHistoryPoint"},"QualityScoreHistorySummary":{"properties":{"period_days":{"type":"integer","minimum":1.0,"title":"Period Days"},"data_points":{"type":"integer","minimum":0.0,"title":"Data Points"},"history":{"items":{"$ref":"#/components/schemas/QualityScoreHistoryPoint"},"type":"array","title":"History"},"current_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Current Score"},"score_trend":{"type":"string","enum":["improving","declining","stable","insufficient_data"],"title":"Score Trend"},"score_change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score Change"}},"type":"object","required":["period_days","data_points","score_trend"],"title":"QualityScoreHistorySummary"},"QualityScoreSummary":{"properties":{"total_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Total Score"},"last_scored_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Scored At"},"version":{"type":"string","title":"Version","default":"5.2"},"algorithm":{"type":"string","title":"Algorithm","default":"v5_leaderboard_policy"},"dimensions":{"items":{"$ref":"#/components/schemas/QualityScoreDimension"},"type":"array","title":"Dimensions"},"multipliers":{"additionalProperties":true,"type":"object","title":"Multipliers"}},"type":"object","required":["total_score"],"title":"QualityScoreSummary"},"QueueStatusItem":{"properties":{"queue":{"type":"string","title":"Queue"},"status":{"type":"string","enum":["ok","degraded","down","unknown"],"title":"Status"},"depth":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Depth"},"warn_threshold":{"type":"integer","title":"Warn Threshold"},"down_threshold":{"type":"integer","title":"Down Threshold"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["queue","status","warn_threshold","down_threshold"],"title":"QueueStatusItem"},"RawMetadata":{"properties":{"onchain":{"anyOf":[{"items":{"$ref":"#/components/schemas/OnchainMetadataItem"},"type":"array"},{"type":"null"}],"title":"Onchain","description":"On-chain metadata from MetadataSet events (key-value pairs with hex values)"},"offchain_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Offchain Uri","description":"Token URI pointing to off-chain metadata (IPFS, HTTP, data URI, etc.)"},"offchain_content":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Offchain Content","description":"Parsed, untrusted off-chain metadata content (original user-uploaded JSON). Contains the raw 'services' (EIP-8004 Jan 2026+) or 'endpoints' (legacy) array before standardization. Use agent.services for the standardized version."}},"type":"object","title":"RawMetadata","description":"Raw metadata from on-chain and off-chain sources"},"RecentDonationItem":{"properties":{"donation_id":{"type":"string","format":"uuid","title":"Donation Id"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"display_wallet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Wallet"},"tier":{"type":"string","title":"Tier"},"amount_usdc":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Usdc"},"amount_display":{"type":"string","title":"Amount Display"},"donated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Donated At"},"is_registered_user":{"type":"boolean","title":"Is Registered User"}},"type":"object","required":["donation_id","user_id","display_name","avatar_url","display_wallet","tier","amount_usdc","amount_display","donated_at","is_registered_user"],"title":"RecentDonationItem"},"RecentDonationsResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/RecentDonationItem"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"RecentDonationsResponse"},"RefreshTokenRequest":{"properties":{"refresh_token":{"type":"string","title":"Refresh Token","description":"Refresh token"}},"type":"object","required":["refresh_token"],"title":"RefreshTokenRequest","description":"Schema for refresh token request"},"RefreshTokenResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","description":"New JWT access token"},"refresh_token":{"type":"string","title":"Refresh Token","description":"New JWT refresh token (token rotation)"},"token_type":{"type":"string","title":"Token Type","description":"Token type","default":"bearer"},"expires_in":{"type":"integer","title":"Expires In","description":"Access token expiration in seconds"}},"type":"object","required":["access_token","refresh_token","expires_in"],"title":"RefreshTokenResponse","description":"Schema for refresh token response"},"ScoreHistoryPoint":{"properties":{"scored_at":{"type":"string","format":"date-time","title":"Scored At","description":"When this score was recorded"},"engagement_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Engagement Score","description":"Engagement score (0-100)"},"service_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Service Score","description":"Service score (0-100)"},"publisher_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Publisher Score","description":"Publisher score (0-100)"},"compliance_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Compliance Score","description":"Compliance score (0-100)"},"momentum_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Momentum Score","description":"Momentum score (0-100)"},"score_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Score Version","description":"Scoring algorithm version"},"algorithm":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Algorithm","description":"Scoring algorithm name"},"quality_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Quality Score","description":"Legacy quality score"},"popularity_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Popularity Score","description":"Legacy popularity score"},"activity_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Activity Score","description":"Legacy activity score"},"validation_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Validation Score","description":"Legacy validation score"},"wallet_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Wallet Score","description":"Legacy wallet score"},"freshness_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Freshness Score","description":"Legacy freshness score"},"total_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Total Score","description":"Weighted total score (0-100)"},"total_feedbacks":{"type":"integer","minimum":0.0,"title":"Total Feedbacks","description":"Total feedbacks at this time"},"total_validations":{"type":"integer","minimum":0.0,"title":"Total Validations","description":"Total validations at this time"},"total_stars":{"type":"integer","minimum":0.0,"title":"Total Stars","description":"Total stars at this time"},"total_watches":{"type":"integer","minimum":0.0,"title":"Total Watches","description":"Total watches at this time"}},"type":"object","required":["scored_at","total_score","total_feedbacks","total_validations","total_stars","total_watches"],"title":"ScoreHistoryPoint","description":"Single score history data point"},"ScoreHistoryResponse":{"properties":{"agent_id":{"type":"string","title":"Agent Id","description":"Agent UUID"},"period_days":{"type":"integer","minimum":1.0,"title":"Period Days","description":"Number of days included in history"},"data_points":{"type":"integer","minimum":0.0,"title":"Data Points","description":"Number of score snapshots"},"history":{"items":{"$ref":"#/components/schemas/ScoreHistoryPoint"},"type":"array","title":"History","description":"Score history data points"},"current_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Current Score","description":"Most recent score"},"score_trend":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Score Trend","description":"Score trend: 'improving', 'declining', 'stable', or 'insufficient_data'"},"score_change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score Change","description":"Score change from oldest to newest (positive = improving)"}},"type":"object","required":["agent_id","period_days","data_points","history"],"title":"ScoreHistoryResponse","description":"Complete score history response for an agent"},"ScoresData":{"properties":{"quality":{"type":"number","title":"Quality","default":0.0},"popularity":{"type":"number","title":"Popularity","default":0.0},"activity":{"type":"number","title":"Activity","default":0.0},"wallet":{"type":"number","title":"Wallet","default":0.0},"freshness":{"type":"number","title":"Freshness","default":0.0},"metadata_completeness":{"type":"number","title":"Metadata Completeness","default":0.0},"last_scored_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Scored At"}},"type":"object","title":"ScoresData","description":"All dimension scores - stored in scores JSONB column\n\nNOTE: validation is intentionally excluded from API responses.\nThe validation system is disabled until the official spec is finalized."},"SetFeaturedRequest":{"properties":{"is_featured":{"type":"boolean","title":"Is Featured","description":"Whether agent should be featured"},"reason":{"type":"string","maxLength":500,"minLength":5,"title":"Reason","description":"Reason for marking/unmarking as featured"}},"type":"object","required":["is_featured","reason"],"title":"SetFeaturedRequest","description":"Request to set featured status"},"SetFeaturedResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"chain_id":{"type":"integer","title":"Chain Id"},"token_id":{"type":"integer","title":"Token Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"is_featured":{"type":"boolean","title":"Is Featured"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","agent_id","chain_id","token_id","name","is_featured","message"],"title":"SetFeaturedResponse","description":"Response for set featured operation"},"StarAgentResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"},"agent_id":{"type":"string","title":"Agent Id"},"user_id":{"type":"string","title":"User Id"},"star_count":{"type":"integer","title":"Star Count"}},"type":"object","required":["success","message","agent_id","user_id","star_count"],"title":"StarAgentResponse","description":"Schema for star agent operation response"},"StatusSummaryResponse":{"properties":{"status":{"type":"string","enum":["ok","degraded","down","unknown"],"title":"Status"},"checked_at":{"type":"string","format":"date-time","title":"Checked At"},"environment":{"type":"string","title":"Environment"},"version":{"type":"string","title":"Version"},"components":{"additionalProperties":{"type":"string","enum":["ok","degraded","down","unknown"]},"type":"object","title":"Components"}},"type":"object","required":["status","checked_at","environment","version","components"],"title":"StatusSummaryResponse"},"StorageFileInfo":{"properties":{"key":{"type":"string","title":"Key","description":"Object key in storage"},"url":{"type":"string","title":"Url","description":"Public URL for accessing the file"},"content_type":{"type":"string","title":"Content Type","description":"MIME type"},"size":{"type":"integer","title":"Size","description":"File size in bytes"},"exists":{"type":"boolean","title":"Exists","description":"Whether file exists"}},"type":"object","required":["key","url","content_type","size","exists"],"title":"StorageFileInfo","description":"File information response"},"StorageStatsResponse":{"properties":{"total_files":{"type":"integer","title":"Total Files"},"total_bytes":{"type":"integer","title":"Total Bytes"},"unique_users":{"type":"integer","title":"Unique Users"},"unique_ips":{"type":"integer","title":"Unique Ips"}},"type":"object","required":["total_files","total_bytes","unique_users","unique_ips"],"title":"StorageStatsResponse","description":"Global storage statistics"},"StorageStatusResponse":{"properties":{"configured":{"type":"boolean","title":"Configured","description":"Whether R2 storage is configured"},"public_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Domain","description":"Public domain for file access"},"max_file_size":{"type":"integer","title":"Max File Size","description":"Maximum file size in bytes"}},"type":"object","required":["configured","max_file_size"],"title":"StorageStatusResponse","description":"Storage service status"},"StorageUploadInfo":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"object_key":{"type":"string","title":"Object Key","description":"R2 object key (hash.ext)"},"content_hash":{"type":"string","title":"Content Hash","description":"SHA-256 content hash"},"uploader_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Uploader User Id","description":"Uploader user ID"},"uploader_wallet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uploader Wallet","description":"Uploader wallet address"},"uploader_ip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uploader Ip","description":"Uploader IP address"},"file_size":{"type":"integer","title":"File Size","description":"File size in bytes"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type","description":"MIME type"},"original_filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Filename","description":"Original filename"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Upload timestamp"}},"type":"object","required":["id","object_key","content_hash","file_size","created_at"],"title":"StorageUploadInfo","description":"Storage upload record info"},"StorageUploadResponse":{"properties":{"hash":{"type":"string","title":"Hash","description":"SHA-256 hash of file content (64 hex chars)"},"key":{"type":"string","title":"Key","description":"Object key in storage (hash.ext)"},"url":{"type":"string","title":"Url","description":"Public URL for accessing the file"},"size":{"type":"integer","title":"Size","description":"File size in bytes"},"content_type":{"type":"string","title":"Content Type","description":"MIME type of the file"},"deduplicated":{"type":"boolean","title":"Deduplicated","description":"True if file already existed (same hash)"}},"type":"object","required":["hash","key","url","size","content_type","deduplicated"],"title":"StorageUploadResponse","description":"Response for file upload"},"StorageUploadsResponse":{"properties":{"uploads":{"items":{"$ref":"#/components/schemas/StorageUploadInfo"},"type":"array","title":"Uploads"},"total":{"type":"integer","title":"Total","description":"Total matching records"}},"type":"object","required":["uploads","total"],"title":"StorageUploadsResponse","description":"List of storage uploads"},"SupportedChainInfo":{"properties":{"chain_id":{"type":"integer","title":"Chain Id","description":"Chain ID (e.g., 1, 11155111)"},"name":{"type":"string","title":"Name","description":"Chain display name (e.g., 'Ethereum Mainnet')"},"key":{"type":"string","title":"Key","description":"Chain key for internal use (e.g., 'eth_mainnet')"},"is_testnet":{"type":"boolean","title":"Is Testnet","description":"Whether this is a testnet"},"enabled":{"type":"boolean","title":"Enabled","description":"Whether chain is enabled for indexing","default":true},"has_registry":{"type":"boolean","title":"Has Registry","description":"Whether registry contracts are deployed","default":false}},"type":"object","required":["chain_id","name","key","is_testnet"],"title":"SupportedChainInfo","description":"Information about a supported blockchain"},"TaskQueueStatusResponse":{"properties":{"status":{"type":"string","enum":["ok","degraded","down","unknown"],"title":"Status"},"checked_at":{"type":"string","format":"date-time","title":"Checked At"},"queues":{"items":{"$ref":"#/components/schemas/QueueStatusItem"},"type":"array","title":"Queues"},"workers":{"$ref":"#/components/schemas/WorkerHeartbeatStatus"},"redis_available":{"type":"boolean","title":"Redis Available"}},"type":"object","required":["status","checked_at","queues","workers","redis_available"],"title":"TaskQueueStatusResponse"},"TopUploaderInfo":{"properties":{"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id"},"wallet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Wallet"},"ip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip"},"upload_count":{"type":"integer","title":"Upload Count"},"total_bytes":{"type":"integer","title":"Total Bytes"}},"type":"object","required":["user_id","wallet","ip","upload_count","total_bytes"],"title":"TopUploaderInfo","description":"Top uploader info for abuse detection"},"TopUploadersResponse":{"properties":{"uploaders":{"items":{"$ref":"#/components/schemas/TopUploaderInfo"},"type":"array","title":"Uploaders"},"hours":{"type":"integer","title":"Hours","description":"Time window in hours"}},"type":"object","required":["uploaders","hours"],"title":"TopUploadersResponse","description":"Top uploaders response"},"UnreadCountResponse":{"properties":{"unread_count":{"type":"integer","title":"Unread Count"}},"type":"object","required":["unread_count"],"title":"UnreadCountResponse","description":"Schema for unread message count"},"UnstarAgentResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"},"agent_id":{"type":"string","title":"Agent Id"},"star_count":{"type":"integer","title":"Star Count"}},"type":"object","required":["success","message","agent_id","star_count"],"title":"UnstarAgentResponse","description":"Schema for unstar agent operation response"},"UserActivityResponse":{"properties":{"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User UUID (if registered user)"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"Ethereum address"},"total_activities":{"type":"integer","title":"Total Activities"},"activities":{"items":{"$ref":"#/components/schemas/ActivityItem"},"type":"array","title":"Activities"}},"type":"object","required":["total_activities","activities"],"title":"UserActivityResponse","description":"Schema for user activity timeline response"},"UserCardResponse":{"properties":{"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User ID (if registered)"},"address":{"type":"string","title":"Address","description":"Primary wallet address"},"ens_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ens Name","description":"ENS domain name if available"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username","description":"Display username"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url","description":"Avatar image URL"},"is_verified":{"type":"boolean","title":"Is Verified","description":"Email/identity verified","default":false},"is_official_validator":{"type":"boolean","title":"Is Official Validator","description":"Official validator status","default":false},"is_certified_validator":{"type":"boolean","title":"Is Certified Validator","description":"Has approved validator certification","default":false},"is_certified_publisher":{"type":"boolean","title":"Is Certified Publisher","description":"Has approved publisher certification","default":false},"publisher_certified_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publisher Certified Name","description":"Platform-assigned certified publisher name"},"reputation_score":{"type":"integer","title":"Reputation Score","description":"User reputation (0-1000)","default":100},"total_agents":{"type":"integer","title":"Total Agents","description":"Number of agents created","default":0},"total_feedbacks":{"type":"integer","title":"Total Feedbacks","description":"Number of feedbacks submitted","default":0},"follower_count":{"type":"integer","title":"Follower Count","description":"Number of followers","default":0},"following_count":{"type":"integer","title":"Following Count","description":"Number of users following","default":0},"is_following":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Following","description":"Whether current user follows this user (null if not authenticated)"}},"type":"object","required":["address"],"title":"UserCardResponse","description":"Lightweight user info for hover cards.\n\nOptimized for fast retrieval (~50ms target) with minimal data.\nUsed when hovering over user addresses in the UI."},"UserCertificationsResponse":{"properties":{"validator_certification":{"anyOf":[{"$ref":"#/components/schemas/ValidatorCertificationResponse"},{"type":"null"}]},"publisher_certification":{"anyOf":[{"$ref":"#/components/schemas/PublisherCertificationResponse"},{"type":"null"}]}},"type":"object","title":"UserCertificationsResponse","description":"User's combined certification status"},"UserCreate":{"properties":{"wallet_address":{"type":"string","maxLength":44,"minLength":32,"title":"Wallet Address"}},"type":"object","required":["wallet_address"],"title":"UserCreate","description":"Schema for user registration"},"UserDeleteChallenge":{"properties":{"user_id":{"type":"string","title":"User Id","description":"User ID requesting deletion"},"primary_wallet":{"type":"string","title":"Primary Wallet","description":"Primary wallet that must sign"},"message":{"type":"string","title":"Message","description":"Message to sign with the wallet"},"nonce":{"type":"string","title":"Nonce","description":"Unique nonce for this request"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Challenge expiration time"}},"type":"object","required":["user_id","primary_wallet","message","nonce","expires_at"],"title":"UserDeleteChallenge","description":"Schema for account deletion challenge response (step 1)"},"UserDeleteConfirm":{"properties":{"signature":{"type":"string","title":"Signature","description":"Signature of the challenge message"},"nonce":{"type":"string","title":"Nonce","description":"Nonce from the challenge"},"chain_id":{"type":"integer","title":"Chain Id","description":"Chain ID for signature verification","default":1}},"type":"object","required":["signature","nonce"],"title":"UserDeleteConfirm","description":"Schema for confirming account deletion with signature (step 2)"},"UserDeleteResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"},"deleted_user_id":{"type":"string","title":"Deleted User Id","description":"ID of the deleted user"},"wallet_addresses":{"items":{"type":"string"},"type":"array","title":"Wallet Addresses","description":"Wallet addresses that were restored to empty user state"},"webhooks_deleted":{"type":"integer","title":"Webhooks Deleted","description":"Number of webhooks deleted","default":0},"new_users_created":{"type":"integer","title":"New Users Created","description":"Number of new empty users created for wallets","default":0}},"type":"object","required":["success","message","deleted_user_id","wallet_addresses"],"title":"UserDeleteResponse","description":"Schema for user deletion response (Apple App Store compliance)"},"UserDonationListItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"status":{"type":"string","title":"Status"},"donor_wallet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Donor Wallet"},"recipient_wallet":{"type":"string","title":"Recipient Wallet"},"chain_id":{"type":"integer","title":"Chain Id"},"network":{"type":"string","title":"Network"},"tx_hash":{"type":"string","title":"Tx Hash"},"token_address":{"type":"string","title":"Token Address"},"token_symbol":{"type":"string","title":"Token Symbol"},"amount_usdc":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Usdc"},"amount_usd":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Usd"},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Settled At"},"verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Verified At"}},"type":"object","required":["id","status","donor_wallet","recipient_wallet","chain_id","network","tx_hash","token_address","token_symbol","amount_usdc","amount_usd","settled_at","verified_at"],"title":"UserDonationListItem"},"UserDonationListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/UserDonationListItem"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"UserDonationListResponse"},"UserDonationRankResponse":{"properties":{"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"},"total_amount_usdc":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Amount Usdc"},"total_amount_display":{"type":"string","title":"Total Amount Display"},"tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tier"},"donation_count":{"type":"integer","title":"Donation Count"},"last_donated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Donated At"},"display_wallet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Wallet"},"is_ranked":{"type":"boolean","title":"Is Ranked"}},"type":"object","required":["rank","total_amount_usdc","total_amount_display","tier","donation_count","last_donated_at","display_wallet","is_ranked"],"title":"UserDonationRankResponse"},"UserFeedbackItem":{"properties":{"id":{"type":"string","title":"Id"},"agent_id":{"type":"string","title":"Agent Id"},"score":{"type":"integer","title":"Score"},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment"},"is_revoked":{"type":"boolean","title":"Is Revoked"},"submitted_at":{"type":"string","format":"date-time","title":"Submitted At"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At"}},"type":"object","required":["id","agent_id","score","is_revoked","submitted_at"],"title":"UserFeedbackItem","description":"Schema for a single feedback in user feedbacks list"},"UserFeedbacksListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/UserFeedbackItem"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"UserFeedbacksListResponse","description":"Schema for paginated user feedbacks list"},"UserResponse":{"properties":{"id":{"type":"string","title":"Id"},"primary_wallet":{"type":"string","title":"Primary Wallet"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"bio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bio"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"twitter_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twitter Handle"},"github_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Github Handle"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"wallets":{"anyOf":[{"items":{"$ref":"#/components/schemas/app__schemas__user__WalletResponse"},"type":"array"},{"type":"null"}],"title":"Wallets"},"is_verified":{"type":"boolean","title":"Is Verified","default":false},"is_official_validator":{"type":"boolean","title":"Is Official Validator","default":false},"is_certified_validator":{"type":"boolean","title":"Is Certified Validator","default":false},"is_certified_publisher":{"type":"boolean","title":"Is Certified Publisher","default":false},"validator_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Validator Tier"},"publisher_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publisher Tier"},"publisher_certified_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publisher Certified Name"},"total_agents":{"type":"integer","title":"Total Agents","default":0},"total_feedbacks":{"type":"integer","title":"Total Feedbacks","default":0},"reputation_score":{"type":"integer","title":"Reputation Score","default":100}},"type":"object","required":["id","primary_wallet","created_at","updated_at"],"title":"UserResponse","description":"Schema for user response"},"UserStatsResponse":{"properties":{"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User UUID (if registered user)"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"Ethereum address"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"total_feedbacks_given":{"type":"integer","title":"Total Feedbacks Given"},"active_feedbacks":{"type":"integer","title":"Active Feedbacks"},"revoked_feedbacks":{"type":"integer","title":"Revoked Feedbacks"},"average_score_given":{"type":"number","title":"Average Score Given"},"total_validations_requested":{"type":"integer","title":"Total Validations Requested"},"total_validations_responded":{"type":"integer","title":"Total Validations Responded"},"total_agents_owned":{"type":"integer","title":"Total Agents Owned"},"total_agents_starred":{"type":"integer","title":"Total Agents Starred"},"is_verified":{"type":"boolean","title":"Is Verified","default":false},"is_official_validator":{"type":"boolean","title":"Is Official Validator","default":false},"last_feedback_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Feedback At"},"last_validation_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Validation At"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["total_feedbacks_given","active_feedbacks","revoked_feedbacks","average_score_given","total_validations_requested","total_validations_responded","total_agents_owned","total_agents_starred"],"title":"UserStatsResponse","description":"Schema for user statistics response"},"UserStorageUsageResponse":{"properties":{"user_id":{"type":"string","format":"uuid","title":"User Id"},"file_count":{"type":"integer","title":"File Count"},"total_bytes":{"type":"integer","title":"Total Bytes"}},"type":"object","required":["user_id","file_count","total_bytes"],"title":"UserStorageUsageResponse","description":"User storage usage"},"UserSummary":{"properties":{"address":{"type":"string","title":"Address"},"ens":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ens"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"validator_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Validator Tier","description":"DEPRECATED: Validator certification is not supported by ERC-8004 spec. Always NULL for new data."}},"type":"object","required":["address"],"title":"UserSummary","description":"Minimal user info for feedback response"},"UserUpdate":{"properties":{"username":{"anyOf":[{"type":"string","maxLength":50,"minLength":3},{"type":"null"}],"title":"Username"},"bio":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Bio"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"twitter_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Twitter Handle"},"github_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Github Handle"}},"type":"object","title":"UserUpdate","description":"Schema for updating user profile"},"UserValidationItem":{"properties":{"id":{"type":"string","title":"Id"},"agent_id":{"type":"string","title":"Agent Id"},"status":{"type":"string","title":"Status"},"vote":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vote"},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","agent_id","status","created_at","updated_at"],"title":"UserValidationItem","description":"Schema for a single validation in user validations list"},"UserValidationsListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/UserValidationItem"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"UserValidationsListResponse","description":"Schema for paginated user validations list"},"V5Dimension":{"properties":{"score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Score","description":"Dimension score (0-100)"},"weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Weight","description":"Dimension weight (0-1)"},"weighted_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Weighted Score","description":"Score * weight * 100 (contribution to total)","default":0.0},"explanation":{"type":"string","title":"Explanation","description":"Human-readable explanation of the score","default":""},"details":{"additionalProperties":true,"type":"object","title":"Details","description":"Dimension-specific details"}},"additionalProperties":true,"type":"object","required":["score","weight"],"title":"V5Dimension","description":"A single v5 dimension with score, weight, and details"},"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"},"ValidatorCertificationAdminAssign":{"properties":{"tier":{"type":"string","pattern":"^(PLATFORM|OFFICIAL|VERIFIED|COMMUNITY)$","title":"Tier"},"reason":{"type":"string","maxLength":1000,"minLength":5,"title":"Reason"},"kyc_verified":{"type":"boolean","title":"Kyc Verified","default":false},"certification_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Certification Expires At"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"}},"type":"object","required":["tier","reason"],"title":"ValidatorCertificationAdminAssign","description":"DEPRECATED: Admin: assign validator tier.\nValidator certification is not supported by the ERC-8004 spec."},"ValidatorCertificationAdminReject":{"properties":{"reason":{"type":"string","maxLength":1000,"minLength":5,"title":"Reason"}},"type":"object","required":["reason"],"title":"ValidatorCertificationAdminReject","description":"DEPRECATED: Admin: reject pending validator certification application"},"ValidatorCertificationAdminRevoke":{"properties":{"reason":{"type":"string","maxLength":1000,"minLength":5,"title":"Reason"}},"type":"object","required":["reason"],"title":"ValidatorCertificationAdminRevoke","description":"DEPRECATED: Admin: revoke approved validator certification"},"ValidatorCertificationCreate":{"properties":{"reason":{"type":"string","maxLength":1000,"minLength":10,"title":"Reason","description":"Why you want to be a validator"},"organization":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Organization"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"}},"type":"object","required":["reason"],"title":"ValidatorCertificationCreate","description":"DEPRECATED: Request to apply for validator certification.\nValidator certification is not supported by the ERC-8004 spec."},"ValidatorCertificationResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"user_id":{"type":"string","format":"uuid","title":"User Id"},"tier":{"type":"string","title":"Tier"},"status":{"type":"string","title":"Status"},"certification_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Certification Reason"},"kyc_verified":{"type":"boolean","title":"Kyc Verified"},"kyc_verified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Kyc Verified At"},"is_active":{"type":"boolean","title":"Is Active"},"is_expired":{"type":"boolean","title":"Is Expired"},"certified_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Certified At"},"certification_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Certification Expires At"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","user_id","tier","status","certification_reason","kyc_verified","kyc_verified_at","is_active","is_expired","certified_at","certification_expires_at","created_at","updated_at"],"title":"ValidatorCertificationResponse","description":"DEPRECATED: Validator certification response.\nValidator certification is not supported by the ERC-8004 spec."},"ValidatorLeaderboardItem":{"properties":{"rank":{"type":"integer","title":"Rank","description":"Validator rank in leaderboard (1-based)"},"validator_address":{"type":"string","title":"Validator Address","description":"Validator wallet address"},"validator_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Validator Name","description":"Validator display name (if set)"},"tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tier","description":"Validator tier (platform, official, verified, community)"},"tier_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tier Label","description":"Human-readable tier label"},"total_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Total Score","description":"Composite leaderboard score (0-100)"},"total_validations":{"type":"integer","title":"Total Validations","description":"Total validations performed","default":0},"successful_validations":{"type":"integer","title":"Successful Validations","description":"Successfully approved validations","default":0},"rejected_validations":{"type":"integer","title":"Rejected Validations","description":"Rejected validations","default":0},"approval_rate":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Approval Rate","description":"Approval rate percentage (0-100)","default":0},"avg_response_time_hours":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Response Time Hours","description":"Average response time in hours"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id","description":"Associated user ID (if linked)"},"first_validation_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Validation At","description":"First validation timestamp"},"last_validation_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Validation At","description":"Most recent validation timestamp"}},"type":"object","required":["rank","validator_address","total_score"],"title":"ValidatorLeaderboardItem","description":"Schema for validator leaderboard item"},"ValidatorLeaderboardResponse":{"properties":{"total":{"type":"integer","title":"Total","description":"Total number of validators matching filters"},"limit":{"type":"integer","title":"Limit","description":"Number of items per page"},"offset":{"type":"integer","title":"Offset","description":"Pagination offset"},"items":{"items":{"$ref":"#/components/schemas/ValidatorLeaderboardItem"},"type":"array","title":"Items","description":"Validator leaderboard items"}},"type":"object","required":["total","limit","offset"],"title":"ValidatorLeaderboardResponse","description":"Schema for validator leaderboard response"},"VerificationRequestResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Status message"},"queued":{"type":"boolean","title":"Queued","description":"Whether verification was queued","default":true},"estimated_check_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Estimated Check At","description":"Estimated time for verification check"}},"type":"object","required":["message"],"title":"VerificationRequestResponse","description":"Response after requesting endpoint verification"},"WalletAgentItem":{"properties":{"chain_id":{"type":"integer","title":"Chain Id"},"token_id":{"type":"integer","title":"Token Id"},"registry_address":{"type":"string","title":"Registry Address"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"},"total_stars":{"type":"integer","title":"Total Stars","default":0},"total_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Score"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["chain_id","token_id","registry_address","created_at","updated_at"],"title":"WalletAgentItem","description":"Agent item in wallet's agent list"},"WalletAgentsListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/WalletAgentItem"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"WalletAgentsListResponse","description":"Paginated list of agents owned by a wallet"},"WalletChainMetricsResponse":{"properties":{"chain_id":{"type":"integer","title":"Chain Id"},"balance":{"type":"string","title":"Balance","description":"Chain-native balance in wei"},"tx_count":{"type":"integer","title":"Tx Count","description":"Transaction count on this chain","default":0},"wallet_age_days":{"type":"integer","title":"Wallet Age Days","description":"Days since first transaction on this chain","default":0},"first_tx_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Tx At"},"last_tx_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Tx At"},"first_tx_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"First Tx Block"},"last_tx_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Tx Block"},"payment_count":{"type":"integer","title":"Payment Count","description":"X402 payment count on this chain","default":0},"total_revenue":{"type":"string","title":"Total Revenue","description":"Total X402 revenue in wei on this chain","default":"0"},"is_contract":{"type":"boolean","title":"Is Contract","description":"Whether address is a contract on this chain","default":false},"metrics_updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Updated At"},"sync_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Error"}},"type":"object","required":["chain_id","balance"],"title":"WalletChainMetricsResponse","description":"Chain-specific wallet metrics entry."},"WalletCreate":{"properties":{"wallet_address":{"type":"string","maxLength":44,"minLength":32,"title":"Wallet Address"}},"type":"object","required":["wallet_address"],"title":"WalletCreate","description":"Schema for creating a new wallet"},"WalletLoginRequest":{"properties":{"wallet_address":{"type":"string","maxLength":44,"minLength":32,"title":"Wallet Address"},"signature":{"type":"string","title":"Signature","description":"Signed message from wallet (EOA/ERC-1271/ERC-6492)"},"nonce":{"type":"string","title":"Nonce","description":"The nonce that was signed"},"chain_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chain Id","description":"Chain ID for signature verification (required for ERC-6492)"}},"type":"object","required":["wallet_address","signature","nonce"],"title":"WalletLoginRequest","description":"Schema for wallet signature login\n\nSupports:\n- EOA signatures (EIP-191): 132 chars\n- ERC-1271 signatures: 132 chars\n- ERC-6492 signatures (Coinbase Embedded Wallet): Variable length (can be 1000+ chars)"},"WalletMergeChallenge":{"properties":{"wallet_address":{"type":"string","title":"Wallet Address"},"message":{"type":"string","title":"Message","description":"Message to sign with the wallet"},"nonce":{"type":"string","title":"Nonce","description":"Unique nonce for this request"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Challenge expiration time"}},"type":"object","required":["wallet_address","message","nonce","expires_at"],"title":"WalletMergeChallenge","description":"Schema for wallet merge challenge response"},"WalletMergeConfirm":{"properties":{"wallet_address":{"type":"string","maxLength":44,"minLength":32,"title":"Wallet Address","description":"Wallet address to merge"},"signature":{"type":"string","title":"Signature","description":"Signature of the challenge message"},"nonce":{"type":"string","title":"Nonce","description":"Nonce from the challenge"}},"type":"object","required":["wallet_address","signature","nonce"],"title":"WalletMergeConfirm","description":"Schema for confirming wallet merge with signature"},"WalletMergeRequest":{"properties":{"wallet_address":{"type":"string","maxLength":44,"minLength":32,"title":"Wallet Address","description":"Wallet address to merge"}},"type":"object","required":["wallet_address"],"title":"WalletMergeRequest","description":"Schema for initiating wallet merge request"},"WalletMergeResult":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"},"merged_wallet":{"type":"string","title":"Merged Wallet"},"transferred_agents":{"type":"integer","title":"Transferred Agents","description":"Number of agents transferred","default":0},"transferred_feedbacks":{"type":"integer","title":"Transferred Feedbacks","description":"Number of feedbacks transferred","default":0},"transferred_validations":{"type":"integer","title":"Transferred Validations","description":"Number of validations transferred","default":0},"transferred_stars":{"type":"integer","title":"Transferred Stars","description":"Number of stars transferred","default":0},"deleted_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deleted User Id","description":"ID of the deleted user (if any)"}},"type":"object","required":["success","message","merged_wallet"],"title":"WalletMergeResult","description":"Schema for wallet merge result"},"WalletMetricsResponse":{"properties":{"address":{"type":"string","title":"Address"},"primary_chain_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Primary Chain Id"},"ens_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ens Name"},"ens_updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ens Updated At"},"balance":{"type":"string","title":"Balance","description":"Balance in wei"},"tx_count":{"type":"integer","title":"Tx Count","description":"Total transaction count","default":0},"wallet_age_days":{"type":"integer","title":"Wallet Age Days","description":"Days since first transaction","default":0},"first_tx_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Tx At"},"last_tx_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Tx At"},"first_tx_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"First Tx Block"},"last_tx_block":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Tx Block"},"payment_count":{"type":"integer","title":"Payment Count","description":"X402 payment count","default":0},"total_revenue":{"type":"string","title":"Total Revenue","description":"Total X402 revenue in wei","default":"0"},"is_agent_wallet":{"type":"boolean","title":"Is Agent Wallet","description":"Whether used as an agent wallet","default":false},"is_contract":{"type":"boolean","title":"Is Contract","description":"Whether address is a contract","default":false},"metrics_updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Updated At"},"sync_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Error"},"total_associated_agents":{"type":"integer","title":"Total Associated Agents","description":"Total number of agents using this wallet","default":0},"associated_agents":{"items":{"$ref":"#/components/schemas/AssociatedAgent"},"type":"array","title":"Associated Agents","description":"Top 10 agents by score using this wallet"},"chain_metrics":{"items":{"$ref":"#/components/schemas/WalletChainMetricsResponse"},"type":"array","title":"Chain Metrics","description":"Per-chain wallet metrics, one entry per collected chain"}},"type":"object","required":["address","balance"],"title":"WalletMetricsResponse","description":"Detailed wallet on-chain metrics\n\nProvides comprehensive on-chain data for this wallet address."},"WalletStatsResponse":{"properties":{"total_agents":{"type":"integer","title":"Total Agents"},"active_agents":{"type":"integer","title":"Active Agents","description":"Agents with activity_score > 50"},"inactive_agents":{"type":"integer","title":"Inactive Agents"},"protocol_distribution":{"additionalProperties":{"type":"integer"},"type":"object","title":"Protocol Distribution","description":"Count of agents by protocol type"},"average_quality_score":{"type":"number","title":"Average Quality Score"},"average_validation_score":{"type":"number","title":"Average Validation Score"},"total_feedbacks":{"type":"integer","title":"Total Feedbacks"},"average_feedback_score":{"type":"number","title":"Average Feedback Score"},"score_distribution":{"additionalProperties":{"type":"integer"},"type":"object","title":"Score Distribution","description":"Feedback score distribution (0-20, 21-40, etc.)"},"total_stars":{"type":"integer","title":"Total Stars"},"total_watches":{"type":"integer","title":"Total Watches"}},"type":"object","required":["total_agents","active_agents","inactive_agents","protocol_distribution","average_quality_score","average_validation_score","total_feedbacks","average_feedback_score","score_distribution","total_stars","total_watches"],"title":"WalletStatsResponse","description":"Detailed wallet statistics\n\nProvides comprehensive analytics for agents owned by this wallet."},"WebEndpoint":{"properties":{"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint"}},"type":"object","title":"WebEndpoint","description":"Web endpoint for human interaction"},"WebhookDeliveryResponse":{"properties":{"id":{"type":"string","title":"Id"},"event_type":{"type":"string","title":"Event Type"},"status":{"type":"string","title":"Status"},"attempts":{"type":"integer","title":"Attempts"},"last_attempt_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Attempt At"},"response_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Status"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","event_type","status","attempts","last_attempt_at","response_status","created_at"],"title":"WebhookDeliveryResponse","description":"Webhook delivery response"},"WebhookRegisterRequest":{"properties":{"webhook_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Webhook Url"},"events":{"items":{"type":"string"},"type":"array","title":"Events","description":"Event types to subscribe to","default":["validation.requested","validation.completed"]}},"type":"object","required":["webhook_url"],"title":"WebhookRegisterRequest","description":"Request to register a webhook"},"WebhookRegistrationListResponse":{"properties":{"id":{"type":"string","title":"Id"},"webhook_url":{"type":"string","title":"Webhook Url"},"events":{"items":{"type":"string"},"type":"array","title":"Events"},"active":{"type":"boolean","title":"Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","webhook_url","events","active","created_at"],"title":"WebhookRegistrationListResponse","description":"Webhook registration response for list (hides secret)"},"WebhookRegistrationResponse":{"properties":{"id":{"type":"string","title":"Id"},"webhook_url":{"type":"string","title":"Webhook Url"},"secret":{"type":"string","title":"Secret"},"events":{"items":{"type":"string"},"type":"array","title":"Events"},"active":{"type":"boolean","title":"Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","webhook_url","secret","events","active","created_at"],"title":"WebhookRegistrationResponse","description":"Webhook registration response"},"WebhookUpdateRequest":{"properties":{"webhook_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Webhook Url"},"events":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Events"},"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Active"}},"type":"object","title":"WebhookUpdateRequest","description":"Request to update webhook"},"WorkerHeartbeatStatus":{"properties":{"status":{"type":"string","enum":["ok","degraded","down","unknown"],"title":"Status"},"total_workers":{"type":"integer","title":"Total Workers"},"fresh_workers":{"type":"integer","title":"Fresh Workers"},"stale_workers":{"type":"integer","title":"Stale Workers"},"newest_heartbeat_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Newest Heartbeat At"},"newest_heartbeat_age_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Newest Heartbeat Age Seconds"},"heartbeat_ttl_seconds":{"type":"integer","title":"Heartbeat Ttl Seconds"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["status","total_workers","fresh_workers","stale_workers","heartbeat_ttl_seconds"],"title":"WorkerHeartbeatStatus"},"app__schemas__agent__AgentSummary":{"properties":{"id":{"type":"string","title":"Id"},"agent_id":{"type":"string","title":"Agent Id","description":"Composite identifier: chain_id:registry_address:token_id"},"token_id":{"type":"string","title":"Token Id"},"chain_id":{"type":"integer","title":"Chain Id"},"chain_type":{"type":"string","title":"Chain Type","description":"Chain type: evm or solana","default":"evm"},"contract_address":{"type":"string","title":"Contract Address"},"is_testnet":{"type":"boolean","title":"Is Testnet","description":"Whether this agent is on a testnet (true) or mainnet (false) chain","default":true},"owner_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Id","description":"Owner user UUID if the owner is registered"},"owner_address":{"type":"string","title":"Owner Address"},"owner_ens":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Ens","description":"Owner's ENS name if available"},"owner_username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Username","description":"Owner's display username if registered"},"owner_avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Avatar Url","description":"Owner's avatar URL if registered"},"owner_publisher_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Publisher Tier","description":"Owner's active publisher certification tier (OFFICIAL, VERIFIED, COMMUNITY). NULL if not certified."},"owner_certified_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Certified Name","description":"Platform-assigned certified publisher name (e.g. 'Uniswap Project Team'). NULL if not certified."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"Sanitized agent avatar/image URL"},"is_verified":{"type":"boolean","title":"Is Verified","default":false},"star_count":{"type":"integer","title":"Star Count","default":0},"supported_protocols":{"items":{"type":"string"},"type":"array","title":"Supported Protocols","description":"Supported protocols (MCP, A2A, OASF, Web, Email)"},"x402_supported":{"type":"boolean","title":"X402 Supported","description":"Whether agent supports X402 payments","default":false},"total_score":{"type":"number","title":"Total Score","description":"Weighted total score (0-100)","default":0.0},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"Backward-compatible leaderboard rank (1-based). Equivalent to network_rank and scoped to the agent's network (mainnet/testnet), not a mixed global rank."},"network_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Network Rank","description":"Leaderboard rank (1-based) within the agent's network (mainnet/testnet). This is the preferred field for new clients."},"health_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Health Score","description":"Cached health score (0-100). NULL if never checked."},"total_feedbacks":{"type":"integer","title":"Total Feedbacks","description":"Total number of feedbacks received","default":0},"average_score":{"type":"number","title":"Average Score","description":"Average feedback score (0-5)","default":0.0},"cross_chain_versions":{"anyOf":[{"items":{"$ref":"#/components/schemas/CrossChainVersionSummary"},"type":"array"},{"type":"null"}],"title":"Cross Chain Versions","description":"All versions of this agent across chains (only in leaderboard with grouping)."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"On-chain registration timestamp (unified from registered_at)"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","agent_id","token_id","chain_id","contract_address","owner_address","created_at","updated_at"],"title":"AgentSummary","description":"Lightweight agent schema for list views (featured, trending, latest, search).\n\nThis schema is optimized for list APIs where we return 10-100 agents at once.\nIt excludes large JSONB fields that are only needed in detail views:\n- raw_metadata (~2KB per agent)\n- parse_status full version (~1.3KB)\n- health_status full version (~1KB)\n- scores full breakdown (~2KB)\n- field_sources (~0.4KB)\n- endpoints/services full version\n\nResult: ~1KB per agent vs ~10KB for full AgentResponse\nReduces API response size from ~250KB to ~25KB for 25 agents."},"app__schemas__feedback__AgentSummary":{"properties":{"token_id":{"type":"string","title":"Token Id"},"chain_id":{"type":"integer","title":"Chain Id"},"registry_address":{"type":"string","title":"Registry Address"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"ens":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ens"}},"type":"object","required":["token_id","chain_id","registry_address"],"title":"AgentSummary","description":"Minimal agent info for feedback response"},"app__schemas__user__WalletResponse":{"properties":{"id":{"type":"string","title":"Id"},"address":{"type":"string","title":"Address"},"is_primary":{"type":"boolean","title":"Is Primary"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","address","is_primary","created_at"],"title":"WalletResponse","description":"Schema for wallet response"},"app__schemas__wallet__WalletResponse":{"properties":{"address":{"type":"string","title":"Address"},"ens_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ens Name"},"balance":{"type":"string","title":"Balance","description":"Balance in wei as string"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"User ID if wallet is linked to an account"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"is_claimed":{"type":"boolean","title":"Is Claimed","description":"Whether wallet is linked to a user account"},"total_agents":{"type":"integer","title":"Total Agents","description":"Number of agents owned by this wallet","default":0},"total_stars":{"type":"integer","title":"Total Stars","description":"Total stars across all owned agents","default":0},"total_watches":{"type":"integer","title":"Total Watches","description":"Total watches across all owned agents","default":0},"total_feedbacks_received":{"type":"integer","title":"Total Feedbacks Received","description":"Total feedbacks received","default":0},"total_validations_received":{"type":"integer","title":"Total Validations Received","description":"Total validations received","default":0},"average_score":{"type":"number","title":"Average Score","description":"Average score across owned agents","default":0.0},"most_popular_agent":{"anyOf":[{"$ref":"#/components/schemas/MostPopularAgent"},{"type":"null"}],"description":"Most popular agent owned by this wallet"},"has_metrics":{"type":"boolean","title":"Has Metrics","description":"Whether wallet has on-chain metrics","default":false},"tx_count":{"type":"integer","title":"Tx Count","description":"Total transaction count","default":0},"payment_count":{"type":"integer","title":"Payment Count","description":"X402 payment count","default":0},"total_revenue":{"type":"string","title":"Total Revenue","description":"Total X402 revenue in wei","default":"0"},"first_tx_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Tx At","description":"First transaction timestamp"},"is_agent_wallet":{"type":"boolean","title":"Is Agent Wallet","description":"Whether used as an agent wallet","default":false},"is_contract":{"type":"boolean","title":"Is Contract","description":"Whether address is a contract","default":false}},"type":"object","required":["address","balance","is_claimed"],"title":"WalletResponse","description":"Comprehensive wallet information response\n\nCombines owner info and wallet data:\n- Basic info (address, ENS, balance)\n- User association (if wallet is linked to a user account)\n- Agent statistics\n- Wallet on-chain metrics"}},"securitySchemes":{"XAccessToken":{"type":"apiKey","in":"header","name":"X-Access-Token","description":"JWT token in X-Access-Token header (recommended)"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token in Authorization: Bearer header (standard auth)"},"XApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"8004scan API key for programmatic access and higher rate limits"}}},"servers":[{"url":"https://api.8004scan.io"}],"security":[{"XAccessToken":[]},{"BearerAuth":[]}]}