# Ethos API

> Ethos is an onchain reputation network. This API exposes credibility scores, reviews, vouches, profiles, XP and reputation markets over REST.

Base URL: `https://api.ethos.network/api/v2`. Send an `X-Ethos-Client` header naming your app, for example `my-app@1.0.0`. Requests without it share one strict rate limit across all anonymous callers.

Most read endpoints are public. Endpoints that require authentication take either a long-lived API key in the `X-Ethos-Api-Key` header, available to profiles with API key access enabled, or a short-lived Privy session token in the `Authorization: Bearer` header. Do not send an API key as a Bearer token. Operations that require the `SessionCookie` scheme are for first-party browser sessions only: they take the HttpOnly cookies set by `POST /auth/exchange`, which itself takes the Privy Bearer token, and mutations are refused with 403 unless the request comes from an Ethos origin. See the API Keys guide on developers.ethos.network.

A **user** is the person record Ethos scores; a **profile** is the on-chain identity a user gets when they join. A user can exist without a profile. Most endpoints accept a **userkey**, a string that identifies a user by any linked account:

- `address:0x…` an Ethereum address
- `profileId:123` an Ethos profile id
- `service:x.com:123456789` an X account by numeric id
- `service:x.com:username:handle` an X account by handle (score, NFT, endorsement and connection lookups; user lookups take the handle as a path parameter instead)
- `service:discord:<id>`, `service:farcaster:<id>`, `service:telegram:<id>`, `service:github:<id>` other linked accounts

Scores range from 0 to 2800 and map to a named level from untrusted to renowned. List endpoints are paginated one of two ways, shown by their response shape: offset pagination takes `limit` and `offset` and returns `{ values, total, limit, offset }`; cursor pagination takes `limit` and `cursor` and returns `{ values, nextCursor }`.

## Reference

- [Full API reference for LLMs](https://api.ethos.network/docs/llms-full.txt): every endpoint with parameters and response shapes, in compact markdown
- [OpenAPI 3.1 spec](https://api.ethos.network/docs/openapi.json)
- [Developer docs](https://developers.ethos.network)
- [API keys](https://developers.ethos.network/api-documentation/api-key-authentication.md): long-lived keys for bots and scripts
- [Vibe coding quickstart](https://developers.ethos.network/api-documentation/vibe-coding-quickstart.md): project setup instructions for agents

## Endpoint groups

- [Activities](https://developers.ethos.network/api-documentation/api-v2/activities.md): Feed items: reviews, vouches, slashes, replies and other on-chain or social actions, fetched by type and id, by transaction hash, or as a feed for a user or project.
- [Ai Images](https://developers.ethos.network/api-documentation/api-v2/ai-images.md): AI-generated images for slashes and broker posts: read the image currently selected for an entity.
- [Announcements](https://developers.ethos.network/api-documentation/api-v2/announcements.md): In-app announcements shown to users and the endpoint to mark them viewed.
- [Api Keys](https://developers.ethos.network/api-documentation/api-v2/api-keys.md): Create, list and revoke long-lived API keys for bots, scripts and integrations. Keys are minted with a SIWE signature.
- [Apps](https://developers.ethos.network/api-documentation/api-v2/apps.md): Registry of third-party apps built on Ethos, as shown on the Built on Ethos page.
- [Benefits](https://developers.ethos.network/api-documentation/api-v2/benefits.md): Perks unlocked by credibility score or for a limited time, including exclusive access codes and their claim flow.
- [Broker](https://developers.ethos.network/api-documentation/api-v2/broker.md): Broker posts: buy, sell, hire, for-hire and bounty posts between users, with watch, report and completion tracking.
- [Categories](https://developers.ethos.network/api-documentation/api-v2/categories.md): Admin-curated groups of users, used for leaderboards and daily tasks: list groups, their summaries and their members.
- [Chains](https://developers.ethos.network/api-documentation/api-v2/chains.md): Blockchains that projects can list, plus the current Base gas price.
- [Contributions](https://developers.ethos.network/api-documentation/api-v2/contributions.md): Daily contribution tasks, streaks and bounties that earn XP. A streak is consecutive days with completed contributions.
- [Curators](https://developers.ethos.network/api-documentation/api-v2/curators.md): The Ethos curators program: the current round’s board of people paid in $WHUF for bringing others to Ethos from X.
- [Endorsements](https://developers.ethos.network/api-documentation/api-v2/endorsements.md): Users the viewer knows who have vouched for or positively reviewed a target user.
- [Ens](https://developers.ethos.network/api-documentation/api-v2/ens.md): Resolve ENS names to addresses and back.
- [Event Markers](https://developers.ethos.network/api-documentation/api-v2/event-markers.md): Dated events overlaid on charts, such as launches or incidents.
- [Exchange Rates](https://developers.ethos.network/api-documentation/api-v2/exchange-rates.md): Current ETH and WHUF prices in USD.
- [Feature Views](https://developers.ethos.network/api-documentation/api-v2/feature-views.md): Records that the current user has dismissed a one-time overlay.
- [Human Verification](https://developers.ethos.network/api-documentation/api-v2/human-verification.md): Humanity bonds: verified users with an established score stake credibility on another account being a real person. Read verification state, find verifiers or request verification.
- [Internal](https://developers.ethos.network/api-documentation/api-v2/internal.md): Endpoints used by Ethos’s own frontends. Not guaranteed to be stable and may change without notice.
- [Invitations](https://developers.ethos.network/api-documentation/api-v2/invitations.md): Invitations to join Ethos: pending invites for an address, invite eligibility and the accepted-invite tree.
- [Karma](https://developers.ethos.network/api-documentation/api-v2/karma.md): Karma: season-based points a user earns for daily contributions, prizes and tips, distinct from XP. Read a user’s ledger and totals, the leaderboard and the latest daily prizes.
- [Llm](https://developers.ethos.network/api-documentation/api-v2/llm.md): LLM-backed utilities: translation, content quality checks and user activity summaries.
- [Markets](https://developers.ethos.network/api-documentation/api-v2/markets.md): Reputation markets (v1) on ethos.markets: market listings, holders, price history and trade simulations.
- [Markets V2](https://developers.ethos.network/api-documentation/api-v2/markets-v2.md): Reputation markets v2: markets keyed by on-chain id, trade and price history, holders, positions and PNL leaderboards.
- [Notifications](https://developers.ethos.network/api-documentation/api-v2/notifications.md): The current user’s in-app notifications and notification settings.
- [Nfts](https://developers.ethos.network/api-documentation/api-v2/nfts.md): NFTs a user holds from tracked collections, validator and Meow Meows holdings, and validator listings.
- [Profiles](https://developers.ethos.network/api-documentation/api-v2/profiles.md): On-chain Ethos profiles. A profile is the on-chain identity created when someone joins; use the users endpoints for the person record and score.
- [Replies](https://developers.ethos.network/api-documentation/api-v2/replies.md): Threaded replies on activities, with pinning and deep-link helpers.
- [Reviews](https://developers.ethos.network/api-documentation/api-v2/reviews.md): Reviews are positive, neutral or negative written assessments one user leaves about another. Use activities to list reviews; these endpoints answer questions about an author and subject pair, or resolve a review from its batch id.
- [Score](https://developers.ethos.network/api-documentation/api-v2/score.md): Credibility scores. A score is a number from 0 to 2800 with a named level. Look up by address, user id or userkey, singly or in bulk, and read score history and recent-update lists.
- [Signatures](https://developers.ethos.network/api-documentation/api-v2/signatures.md): Server-signed payloads required by some on-chain actions, such as registering an address.
- [Slash](https://developers.ethos.network/api-documentation/api-v2/slash.md): Slashes: staked accusations against a user. Supporters who vouched for, positively reviewed or verified a slashed user can be penalized.
- [Stats](https://developers.ethos.network/api-documentation/api-v2/stats.md): Network-wide statistics such as score distribution.
- [System](https://developers.ethos.network/api-documentation/api-v2/system.md): Health checks and transaction processing status.
- [Users](https://developers.ethos.network/api-documentation/api-v2/users.md): The aggregated person record Ethos scores. Look a user up by address, username, profile id, or X, Discord, Farcaster or Telegram account, in bulk or singly, or search by name.
- [Votes](https://developers.ethos.network/api-documentation/api-v2/votes.md): Upvotes and downvotes on activities, and aggregated vote stats.
- [Vouches](https://developers.ethos.network/api-documentation/api-v2/vouches.md): Vouches are stakes one profile places on another as a signal of trust. Query vouches with filters, or check pair state, mutual vouchers and fees.
- [Wallets](https://developers.ethos.network/api-documentation/api-v2/wallets.md): On-chain actions signed by the user’s Ethos Everywhere wallet: reviews, votes, replies, invites, vouches, humanity bonds, market trades and WHUF sends, plus the wallet’s transaction list. First-party browser sessions only: needs the session cookies from /auth/exchange and an Ethos origin.
- [Whuffies](https://developers.ethos.network/api-documentation/api-v2/whuffies.md): WHUF token supply, balances, reward pool, price guarantee and token sale phase.
- [Xp](https://developers.ethos.network/api-documentation/api-v2/xp.md): Experience points: totals per user and season, timelines, and XP tips between users.