Introduction
Welcome to the official API documentation for Ethos Network. This documentation provides detailed information about the Ethos API endpoints, request/response formats, and data models.
These docs are available at https://developers.ethos.network/
Getting Started
Section titled “Getting Started”Ethos offers a comprehensive RESTful API that allows developers to interact with the Ethos Network. The API is organized around standard HTTP methods and uses standard HTTP response codes.
Whitepaper
Section titled “Whitepaper”For a complete overview of the Ethos Network, including its mechanisms and governance model, please refer to the Ethos Whitepaper.
Base URL
Section titled “Base URL”All API requests should be made to the following base URL:
https://api.ethos.networkAuthentication
Section titled “Authentication”Some API endpoints require authentication using a Privy token. These are usually endpoints meant to be used in the context of an active user session — for example, when performing actions tied to the currently logged-in user.
If authentication is required, you must include a valid token in the Authorization header:
Authorization: Bearer <your_privy_token>The token is stored in a privy-token cookie under the app.ethos.network domain. Note, this token is short-lived and expires after 1 hour.
⚠️ Important notes:
Section titled “⚠️ Important notes:”- Most developers won’t need to use this token directly — many endpoints are public or free to use.
- Tokens are tied to the current user session and are only needed when working within that user’s authenticated context.
API Keys
Section titled “API Keys”For programmatic access (bots, scripts, CI/CD), you can create long-lived API keys using a SIWE signature. See API Keys for a quick start and full reference.
Client Identification
Section titled “Client Identification”To help us monitor and manage usage across different integrations, all API requests must include the X-Ethos-Client header.
This header should contain the name of your product or integration, and may optionally include a version number (e.g., my-app or my-app@1.0.0).
X-Ethos-Client: my-cool-app@1.2.3Including this header helps us:
- Attribute traffic to your app
- Diagnose issues faster
- Ensure fair and efficient resource allocation
Ethos Everywhere Wallet
Section titled “Ethos Everywhere Wallet”Ethos Everywhere Wallet brings Ethos functionality into partner applications, allowing users to post reviews, vote, and reply directly from those apps without wallet popups or manual transaction signing. This creates a seamless user experience while maintaining security through server-side managed wallets.
For Partners:
- To integrate Ethos Everywhere Wallet into your application, see the Ethos Everywhere Wallet Partner Guide
- Becoming an allowlisted partner requires domain verification and a security review
- Gas sponsorship is available for qualified users based on credibility score
- Endpoints require JWT authentication; authentication status and wallet balance is available via API
- All wallet endpoints are documented in the API v2 reference under the “wallets” tag
LLM-ready Documentation
Section titled “LLM-ready Documentation”Ethos API documentation is LLM-optimized, enabling AI-powered developer tools like ChatGPT, Claude, Cursor, GitHub Copilot, and other LLM assistants to retrieve accurate, contextual responses.
Developers can ask questions like “How do I get the score for a specific profile?” or “What’s the structure of an activity object?” — and receive precise answers powered by our official API documentation.
Resources
Section titled “Resources”-
OpenAPI v3 spec
The full schema of our public API in OpenAPI format, including available endpoints, methods, parameters, and response structures.
👉 https://api.ethos.network/docs/openapi.json -
LLM discovery files
These files help large language models find the right endpoint without reading the full reference. They are generated from the OpenAPI spec and follow the llms.txt convention:
- https://api.ethos.network/docs/llms.txt — endpoint groups with a one-line description each
- https://api.ethos.network/docs/llms-full.txt — every endpoint with parameters and response shapes
Userkeys
Section titled “Userkeys”Some APIs accept a userkey as a user identifier. Below are the supported formats:
| Format | Description |
|---|---|
profileId:<id> | Ethos profile ID Example: |
address:<address> | Ethereum address Example: |
service:discord:<id> | Discord user ID Example: |
service:farcaster:<id> | Farcaster user ID Example: |
service:telegram:<id> | Telegram user ID Example: |
service:x.com:<id> | Twitter (x.com) user ID Example: |
service:x.com:username:<username> | Twitter (x.com) username Example: |