{
 "openapi": "3.1.0",
 "info": {
  "title": "Agent of Agents",
  "version": "1.0.0",
  "description": "Every ERC-8004 agent on 10+ chains in one index: who answers (live A2A / MCP / web checks), who earns (x402 and direct payments), who made them, their feedback, and which ones are spam or copies. Facts from a live index.\n\nSign in with a wallet: POST https://21411.8004.im/auth/challenge {\"address\":\"0x…\"} → sign the returned message with that wallet (personal_sign) → POST https://21411.8004.im/auth/token {\"address\",\"message\",\"signature\"} → send \"Authorization: Bearer <token>\" (valid 24 h, works on all our agents). Signed in on https://www.erc8004.markets/chat? Use \"API token\" there."
 },
 "servers": [
  {
   "url": "https://21411.8004.im"
  }
 ],
 "components": {
  "securitySchemes": {
   "wallet": {
    "type": "http",
    "scheme": "bearer"
   }
  }
 },
 "security": [
  {
   "wallet": []
  }
 ],
 "paths": {
  "/auth/challenge": {
   "post": {
    "summary": "Message to sign",
    "security": [],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "address": {
          "type": "string"
         }
        },
        "required": [
         "address"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/auth/token": {
   "post": {
    "summary": "Bearer token (24 h) for a signed message",
    "security": [],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "address": {
          "type": "string"
         },
         "message": {
          "type": "string"
         },
         "signature": {
          "type": "string"
         }
        },
        "required": [
         "address",
         "message",
         "signature"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/v1/me": {
   "get": {
    "summary": "Your tier and today's quota for this agent",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/ask": {
   "post": {
    "summary": "Ask Agent of Agents in plain words",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "q": {
          "type": "string"
         }
        },
        "required": [
         "q"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/find_agents": {
   "post": {
    "summary": "Search ERC-8004 agents: by name or words (q), chain, spam label (ok by default; suspect, spam, any), endpoint kind (a2a, mcp, x402, web), answering endpoints only (live), registered in the last N days. Without q / kind / live: newest first.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "q": {
          "type": "string"
         },
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         },
         "label": {
          "type": "string",
          "enum": [
           "ok",
           "suspect",
           "spam",
           "any"
          ]
         },
         "kind": {
          "type": "string",
          "enum": [
           "a2a",
           "mcp",
           "x402",
           "web"
          ]
         },
         "live": {
          "type": "boolean",
          "description": "only agents whose endpoint answered at the last check"
         },
         "days": {
          "type": "number"
         },
         "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/new_agents": {
   "post": {
    "summary": "Newly registered non-spam agents over the last N days (1–30), answering endpoints first, plus how many registered in 24 h / 7 d.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         },
         "days": {
          "type": "number"
         },
         "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/top_rated": {
   "post": {
    "summary": "Agents with the most reputation feedback from distinct reviewers (spam reviewers left out), with average score.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         },
         "min_reviewers": {
          "type": "integer"
         },
         "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/agent_card": {
   "post": {
    "summary": "Everything about one agent: name, description, spam label and why, owner, creator and its label, endpoints and whether they answer, feedback, protocols used, the same agent on other chains. Give chain + id, or a name.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         },
         "id": {
          "type": "integer",
          "description": "agent id on that chain"
         },
         "name": {
          "type": "string",
          "description": "agent name, when the chain / id are not known"
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/same_agent": {
   "post": {
    "summary": "The same agent on other chains (verified / strong links) and possible matches (weak claims).",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         },
         "id": {
          "type": "integer",
          "description": "agent id on that chain"
         },
         "name": {
          "type": "string",
          "description": "agent name, when the chain / id are not known"
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/agent_feedback": {
   "post": {
    "summary": "One agent's reputation feedback: reviewers, scores, tags, revoked ones and spam reviewers.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         },
         "id": {
          "type": "integer",
          "description": "agent id on that chain"
         },
         "name": {
          "type": "string",
          "description": "agent name, when the chain / id are not known"
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/top_creators": {
   "post": {
    "summary": "Addresses that registered the most agents, optionally only spam / suspect / platform / ok creators, with the reasons for their label.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         },
         "label": {
          "type": "string",
          "enum": [
           "spam",
           "suspect",
           "platform",
           "ok"
          ]
         },
         "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/address_profile": {
   "post": {
    "summary": "One address: agents it created (per chain, with its creator label and how many of them are spam), agents it owns, agents using it as their agent wallet.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "address": {
          "type": "string",
          "description": "0x… address"
         },
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         }
        },
        "required": [
         "address"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/spam_overview": {
   "post": {
    "summary": "How much of the registry is spam: ok / suspect / spam / not judged per chain, spam creators, spam reviewers, rescued agents, the biggest creators, and the labelling rules.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/chain_stats": {
   "post": {
    "summary": "Per-chain numbers: agents, new in 24 h / 7 d, non-spam, A2A / MCP / x402, feedback, endpoint checks, sync state.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/cross_chain": {
   "post": {
    "summary": "Agents registered on several chains: links found (verified / strong / weak), entities, claims waiting.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         },
         "level": {
          "type": "string",
          "enum": [
           "verified",
           "strong",
           "weak"
          ]
         },
         "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/protocols": {
   "post": {
    "summary": "On-chain protocols ERC-8004 agents use (tracked): agents, events, volume.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "q": {
          "type": "string"
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/protocol_stats": {
   "post": {
    "summary": "One protocol (slug, e.g. priors, hookr-agent-gate): totals, top agents, recent events, last 30 days.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "slug": {
          "type": "string"
         }
        },
        "required": [
         "slug"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/protocol_agents": {
   "post": {
    "summary": "Agents using one protocol, by volume.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "slug": {
          "type": "string"
         },
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         },
         "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50
         }
        },
        "required": [
         "slug"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/priors_credit": {
   "post": {
    "summary": "Priors credit (Robinhood Chain): agents with credit lines, ranked by credit score, line, amount repaid, loans repaid or amount borrowed now; totals and defaults.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "sort": {
          "type": "string",
          "enum": [
           "score",
           "line",
           "repaid",
           "loans",
           "borrowed"
          ]
         },
         "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/protocol_candidates": {
   "post": {
    "summary": "Contracts the index discovered agents using (not yet tracked protocols): why each is interesting.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/top_earners": {
   "post": {
    "summary": "Agents that earn the most: stablecoin payments received by their x402 payment addresses over the last N days (default 30), with payments, payers and the share relayed by x402 facilitators. x402_only=true counts only facilitator-relayed payments.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         },
         "days": {
          "type": "number"
         },
         "x402_only": {
          "type": "boolean"
         },
         "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  },
  "/v1/tools/agent_earnings": {
   "post": {
    "summary": "One agent's earnings: its x402 payment addresses and price, earned in 24 h / 7 d / 30 d / all time, payers, latest payments, daily totals.",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "chain": {
          "type": "string",
          "description": "chain short name: base, bnb, arc, eth, robinhood, avax, arb, op, polygon, tempo"
         },
         "id": {
          "type": "integer",
          "description": "agent id on that chain"
         },
         "name": {
          "type": "string",
          "description": "agent name, when the chain / id are not known"
         }
        },
        "required": []
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "description": "Sign-in needed"
     },
     "429": {
      "description": "Daily quota used"
     }
    }
   }
  }
 }
}