# 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

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

For a complete overview of the Ethos Network, including its mechanisms and governance model, please refer to the [Ethos Whitepaper](https://whitepaper.ethos.network).

### Base URL

All API requests should be made to the following base URL:

```
https://api.ethos.network
```

### 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:

```http
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:

* 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

For programmatic access (bots, scripts, CI/CD), you can create long-lived API keys using a [SIWE](https://eips.ethereum.org/EIPS/eip-4361) signature. See [API Keys](https://developers.ethos.network/api-documentation/api-key-authentication) for a quick start and full reference.

### 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`).

```http
X-Ethos-Client: my-cool-app@1.2.3
```

{% hint style="warning" %}
Required: Requests without this header may be subject to rate limiting.
{% endhint %}

Including this header helps us:

* Attribute traffic to your app
* Diagnose issues faster
* Ensure fair and efficient resource allocation

### 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](https://developers.ethos.network/api-documentation/ethos-everywhere-wallet-integration)
* 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](https://developers.ethos.network/api-documentation/api-v2) under the "wallets" tag

### 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

* **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 discover and index relevant documentation automatically. They are auto-generated by GitBook and follow an emerging open standard:
  * <https://developers.ethos.network/llms.txt> — high-level metadata, e.g. docs structure and main entry points
  * <https://developers.ethos.network/llms-full.txt> — detailed references to all public documentation pages for deeper LLM indexing

### Userkeys

Some APIs accept a `userkey` as a user identifier. Below are the supported formats:

<table><thead><tr><th width="325.59375">Format</th><th>Description</th></tr></thead><tbody><tr><td><code>profileId:&#x3C;id></code></td><td><p>Ethos profile ID</p><p>Example: <code>profileId:10</code></p></td></tr><tr><td><code>address:&#x3C;address></code></td><td><p>Ethereum address</p><p>Example: <code>address:0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045</code></p></td></tr><tr><td><code>service:discord:&#x3C;id></code></td><td><p>Discord user ID</p><p>Example: <code>service:discord:797130033613242441</code></p></td></tr><tr><td><code>service:farcaster:&#x3C;id></code></td><td><p>Farcaster user ID</p><p>Example: <code>service:farcaster:1112412</code></p></td></tr><tr><td><code>service:telegram:&#x3C;id></code></td><td><p>Telegram user ID</p><p>Example: <code>service:telegram:167380455</code></p></td></tr><tr><td><code>service:x.com:&#x3C;id></code></td><td><p>Twitter (x.com) user ID</p><p>Example: <code>service:x.com:295218901</code></p></td></tr><tr><td><code>service:x.com:username:&#x3C;username></code></td><td><p>Twitter (x.com) username</p><p>Example: <code>service:x.com:username:VitalikButerin</code></p></td></tr></tbody></table>