Skip to content
EthosEthosDevelopers

API Keys

API keys let you call any profile-scoped Ethos endpoint without a browser session. You sign a one-time SIWE message with your wallet, receive a key, and include it in the X-Ethos-Api-Key header on every request.

Prerequisites: an Ethos profile linked to your wallet, and API key access enabled for your account.

Quick start

Section titled “Quick start”

Create a key, send an XP tip, revoke the key — all in one script. Or try the interactive playground to run each step in your browser.

import { privateKeyToAccount } from "viem/accounts";
import { createSiweMessage } from "viem/siwe";


const API = "https://api.ethos.network/api/v2";
const CLIENT = "my-bot@1.0.0"; // identifies your app


const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");


// --- 1. Create API key ---


const message = createSiweMessage({
  domain: "api.ethos.network",
  address: account.address,
  statement: "Create Ethos API key",
  uri: "https://api.ethos.network",
  version: "1",
  chainId: 8453, // Base
  nonce: crypto.randomUUID().replaceAll("-", ""),
  issuedAt: new Date(),
  expirationTime: new Date(Date.now() + 10 * 60 * 1000), // must be within 10 min
});


const signature = await account.signMessage({ message });


const keyResp = await fetch(`${API}/api-keys`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Ethos-Client": CLIENT },
  body: JSON.stringify({
    address: account.address,
    message,
    signature,
    name: "my-bot",
  }),
});


if (!keyResp.ok) throw new Error(`Create key failed: ${await keyResp.text()}`);


const { id: keyId, token } = await keyResp.json();
console.log("Key created:", keyId);


// --- 2. Send XP tip ---


const tipResp = await fetch(`${API}/xp/tip`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Ethos-Api-Key": token,
    "X-Ethos-Client": CLIENT,
  },
  body: JSON.stringify({
    receiverUserkey: "profileId:1",
    amount: 5,
    message: "5 XP, 10 lines of code — developers.ethos.network",
  }),
});


if (!tipResp.ok) throw new Error(`Tip failed: ${await tipResp.text()}`);


const tip = await tipResp.json();
console.log(`Tip #${tip.tipId} sent. Balance: ${tip.senderNewBalance} XP`);


// --- 3. Revoke key ---


const revokeResp = await fetch(`${API}/api-keys/${keyId}`, {
  method: "DELETE",
  headers: { "X-Ethos-Api-Key": token, "X-Ethos-Client": CLIENT },
});


if (!revokeResp.ok) throw new Error(`Revoke failed: ${await revokeResp.text()}`);
console.log("Key revoked");

Creating a key

Section titled “Creating a key”

Key creation uses a SIWE (Sign-In with Ethereum) signature to prove wallet ownership. The server verifies the signature and returns a JWT-based API key.

SIWE message requirements

Section titled “SIWE message requirements”
Field Value Notes
domain api.ethos.network Must match exactly
chainId 8453 Base mainnet
expirationTime Within 10 minutes Required — messages without it are rejected
nonce Random hex string Single-use — the server rejects replayed nonces. Generate a fresh one for every request.
uri https://api.ethos.network
version 1

Request: POST /api/v2/api-keys

Section titled “Request: POST /api/v2/api-keys”
Field Type Required Description
address string Yes Your Ethereum address (0x-prefixed, checksummed)
message string Yes The SIWE message you signed
signature string Yes ECDSA signature (0x-prefixed, 132 hex chars)
name string Yes Label for this key (1-100 chars)
expiresAt string No ISO 8601 datetime. Default: 90 days. Max: 365 days.

Response

Section titled “Response”
{
  "id": "cm...",
  "token": "ethos_eyJhbGci...",
  "name": "my-bot",
  "expiresAt": "2026-06-25T00:00:00.000Z"
}

Authenticating requests

Section titled “Authenticating requests”

Include the key in the X-Ethos-Api-Key header on every request:

X-Ethos-Api-Key: ethos_eyJhbGci...
X-Ethos-Client: my-bot@1.0.0

The key authenticates as the Ethos profile that created it. All profile-scoped endpoints (tips, reviews, votes, vouches) work the same way they do with browser session auth.

Revoking a key

Section titled “Revoking a key”
DELETE /api/v2/api-keys/{id}

Pass the id returned when you created the key. Revocation takes effect immediately — subsequent requests with the revoked key return 401 Unauthorized.

You can revoke a key using the key itself (as shown in the quick start) or with browser session auth.

Reference

Section titled “Reference”

Key lifecycle

Section titled “Key lifecycle”
Property Value
Default expiry 90 days
Maximum expiry 365 days
Active keys per profile 25
Usage tracking lastUsedAt updated per request (throttled to once per minute)

Endpoints

Section titled “Endpoints”
Method Path Auth
POST /api/v2/api-keys None (SIWE signature in body)
GET /api/v2/api-keys API key or browser session
DELETE /api/v2/api-keys/{id} API key or browser session

Error codes

Section titled “Error codes”
HTTP Code Meaning
400 INVALID_AMOUNT XP tip amount must be a positive integer
400 CANNOT_TIP_SELF Sender and receiver are the same profile
400 INSUFFICIENT_XP Not enough XP in your balance
401 — Invalid, expired, or revoked API key
403 — API key access not enabled for this profile
404 RECEIVER_NOT_FOUND No Ethos user matches the receiver userkey
404 KEY_NOT_FOUND Key ID not found or not owned by you