{
  "openapi": "3.1.0",
  "info": {
    "title": "Ethos API over x402",
    "version": "1.0.0",
    "description": "Read-only Ethos reputation lookups paid per request ($0.001 USDC on Base) through the x402 protocol. The full API, free with an X-Ethos-Client header, is documented at https://developers.ethos.network/.",
    "x-guidance": "Ethos is a reputation network for crypto: people review each other, vouch with staked ETH, and link wallets and social accounts to one profile. These routes answer \"can I trust this wallet, X account or person?\" for an AI agent, paid per request so no sign-up is needed. Every route is a GET returning JSON for $0.001 in USDC on Base (eip155:8453) via the x402 exact scheme: call it, read the 402's PAYMENT-REQUIRED header, retry with PAYMENT-SIGNATURE. Which route: /x402/score/{userkey} for a quick trust check (score 0 to 2800; below 800 untrusted, 800 to 1199 questionable, 1200 to 1399 neutral, 1400+ increasingly reputable up to renowned); /x402/user/x/{handle} or /x402/user/address/{address} for the full profile behind an X handle or wallet, including every linked account; /x402/users/search?query= when you only have a name or fragment; /x402/xp/{userkey} to weigh how much history backs a score. A userkey is address:0x…, profileId:<n>, service:x.com:username:<handle>, service:x.com:<account id>, service:discord:<id> or service:telegram:<id>. Typical flows: before a trade or transfer, look up the counterparty address; when a user asks about an account, search by name, then score the match; to rank or filter accounts, score each. Scores reflect peer judgement and can be gamed at the margins, so treat them as a strong signal, not a verdict. The same data is free on https://api.ethos.network/api/v2 with an X-Ethos-Client header (250+ operations, including writes with an API key); see https://developers.ethos.network/api-documentation/agents-x402. Related x402 service: https://who-supported.ethos.network answers who promoted a token or project on X and how credible those accounts are."
  },
  "servers": [
    {
      "url": "https://developers.ethos.network"
    }
  ],
  "paths": {
    "/x402/score/{userkey}": {
      "get": {
        "operationId": "score_userkey",
        "summary": "Credibility score for a userkey",
        "description": "Is this wallet, X account or person trustworthy? Ethos credibility score (0 to 2800) and level, from untrusted to renowned, built from peer reviews, ETH-backed vouches, slashes and linked on-chain and social history. Use it before trading with, following, quoting or paying an unknown counterparty, to rank accounts by reputation, or to flag likely scams and bots. Takes an EVM address, X handle or account id, Discord or Telegram id, or Ethos profile id.",
        "tags": [
          "x402"
        ],
        "parameters": [
          {
            "name": "userkey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "An Ethos userkey: address:0x… (EVM address), profileId:<n>, service:x.com:<X account id>, service:x.com:username:<X handle>, service:discord:<id> or service:telegram:<id>."
            }
          }
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.001"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "x-x402": {
          "price": "$0.001",
          "example": "https://developers.ethos.network/x402/score/service%3Ax.com%3Ausername%3Aethos_network"
        },
        "responses": {
          "200": {
            "description": "The lookup.",
            "content": {
              "application/json": {
                "example": {
                  "score": 2441,
                  "level": "revered"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    },
    "/x402/user/x/{handle}": {
      "get": {
        "operationId": "user_x_handle",
        "summary": "Ethos user by X (Twitter) handle or account id",
        "description": "Who is behind an X (Twitter) handle, and can they be trusted? The Ethos profile for a handle or numeric account id: display name, credibility score and status, every wallet address and social account linked to the same person, XP, influence factor, and how many positive, neutral and negative reviews and vouches they have received. Use it to vet an account before engaging, resolve a handle to its wallets, or enrich a mention with reputation.",
        "tags": [
          "x402"
        ],
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "X handle without the @, or the numeric X account id."
            }
          }
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.001"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "x-x402": {
          "price": "$0.001",
          "example": "https://developers.ethos.network/x402/user/x/ethos_network"
        },
        "responses": {
          "200": {
            "description": "The lookup.",
            "content": {
              "application/json": {
                "example": {
                  "id": 32936,
                  "profileId": 1,
                  "displayName": "Ethos",
                  "username": "ethos_network",
                  "avatarUrl": "https://pbs.twimg.com/profile_images/2074951227599646720/85k3GJ-s.jpg",
                  "score": 2441,
                  "status": "ACTIVE",
                  "userkeys": [
                    "profileId:1",
                    "service:x.com:1234567890",
                    "address:0x1234…"
                  ],
                  "xpTotal": 4076702,
                  "influenceFactor": 276,
                  "stats": {
                    "review": {
                      "received": {
                        "positive": 120,
                        "neutral": 3,
                        "negative": 2
                      }
                    },
                    "vouch": {
                      "received": {
                        "count": 40
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    },
    "/x402/user/address/{address}": {
      "get": {
        "operationId": "user_address_address",
        "summary": "Ethos user by EVM address",
        "description": "Who owns this wallet, and what is their reputation? The Ethos profile holding an EVM address: display name, X handle and other linked accounts, credibility score and status, XP, influence factor, and review and vouch counts. Use it to attach a name and trust level to a counterparty address before a trade, transfer, airdrop or allowlist decision, or to screen addresses in a transaction for known bad actors.",
        "tags": [
          "x402"
        ],
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[0-9a-fA-F]{40}$",
              "description": "EVM address, 0x-prefixed."
            }
          }
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.001"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "x-x402": {
          "price": "$0.001",
          "example": "https://developers.ethos.network/x402/user/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
        },
        "responses": {
          "200": {
            "description": "The lookup.",
            "content": {
              "application/json": {
                "example": {
                  "id": 32936,
                  "profileId": 1,
                  "displayName": "vitalik.eth",
                  "username": null,
                  "avatarUrl": "https://pbs.twimg.com/profile_images/2074951227599646720/85k3GJ-s.jpg",
                  "score": 1311,
                  "status": "INACTIVE",
                  "userkeys": [
                    "profileId:1",
                    "service:x.com:1234567890",
                    "address:0x1234…"
                  ],
                  "xpTotal": 4076702,
                  "influenceFactor": 276,
                  "stats": {
                    "review": {
                      "received": {
                        "positive": 120,
                        "neutral": 3,
                        "negative": 2
                      }
                    },
                    "vouch": {
                      "received": {
                        "count": 40
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    },
    "/x402/users/search": {
      "get": {
        "operationId": "users_search",
        "summary": "Search Ethos users",
        "description": "Find a person or project on Ethos when you only have a name, a partial handle or part of an address. Returns matching profiles with credibility score, status, linked wallets and social accounts, paginated. The starting point when a user asks about someone by name: search, pick the match, then score or profile it by userkey. Also useful for disambiguating impersonators from the real account.",
        "tags": [
          "x402"
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Name, handle or address fragment to search for."
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "description": "Results per page, default 10."
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Results to skip, for paging."
            }
          }
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.001"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "x-x402": {
          "price": "$0.001",
          "example": "https://developers.ethos.network/x402/users/search?query=vitalik&limit=5"
        },
        "responses": {
          "200": {
            "description": "The lookup.",
            "content": {
              "application/json": {
                "example": {
                  "values": [
                    {
                      "id": 32936,
                      "profileId": 1,
                      "displayName": "Ethos",
                      "username": "ethos_network",
                      "avatarUrl": "https://pbs.twimg.com/profile_images/2074951227599646720/85k3GJ-s.jpg",
                      "score": 2441,
                      "status": "ACTIVE",
                      "userkeys": [
                        "profileId:1",
                        "service:x.com:1234567890",
                        "address:0x1234…"
                      ],
                      "xpTotal": 4076702,
                      "influenceFactor": 276,
                      "stats": {
                        "review": {
                          "received": {
                            "positive": 120,
                            "neutral": 3,
                            "negative": 2
                          }
                        },
                        "vouch": {
                          "received": {
                            "count": 40
                          }
                        }
                      }
                    }
                  ],
                  "total": 1,
                  "limit": 5,
                  "offset": 0
                }
              }
            }
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    },
    "/x402/xp/{userkey}": {
      "get": {
        "operationId": "xp_userkey",
        "summary": "Total XP for a userkey",
        "description": "How active and invested is this person in the Ethos reputation network? Total XP earned across all seasons for a userkey (address, X handle or id, Discord or Telegram id, or profile id). XP accrues from reviews, vouches, invitations and other contributions, so it separates long-standing, engaged members from fresh or dormant accounts. Use it alongside the credibility score to weigh how much history stands behind a reputation.",
        "tags": [
          "x402"
        ],
        "parameters": [
          {
            "name": "userkey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "An Ethos userkey: address:0x… (EVM address), profileId:<n>, service:x.com:<X account id>, service:x.com:username:<X handle>, service:discord:<id> or service:telegram:<id>."
            }
          }
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.001"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "x-x402": {
          "price": "$0.001",
          "example": "https://developers.ethos.network/x402/xp/profileId%3A1"
        },
        "responses": {
          "200": {
            "description": "The lookup.",
            "content": {
              "application/json": {
                "example": 4076702
              }
            }
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    }
  }
}