⚙️Introduction

The KEX Agent API allows developers to integrate AI-powered agents into their games and applications. This guide covers authentication, rate limits, and the available REST and WebSocket endpoints.

Getting Started

Obtain an API Key

Request an API key from the KEX team to begin using the service. Keep your key secure; it is required for all API requests.

Credits

The API operates on a credit system linked to your KEX account. Sending a message costs 1 credit. Listing resources and retrieving conversation history are free. If your credit balance drops to zero, API calls that require credits will return a 402 Payment Required error.

Authentication

Include your API key as a Bearer token in the Authorization header.

Authorization: Bearer kex_dev_your_api_key_here

For WebSocket connections, pass the key as a query parameter named key.

wss://ws.kex.gg/v1/ws?key=kex_dev_your_api_key_here

Rate Limiting

Each API key is limited to 100 requests per minute. Responses include these headers to help track usage:

  • X-RateLimit-Limit: Maximum number of requests per window.

  • X-RateLimit-Remaining: Requests left in the current window.

  • X-RateLimit-Reset: Unix timestamp when the limit resets.

Exceeding the limit results in a 429 Too Many Requests error.

REST API

Base URL: https://api.kex.gg

List Agents

GET /v1/agents

Retrieves all publicly available agents. This endpoint is free.

curl "https://api.kex.gg/v1/agents" \
  -H "Authorization: Bearer kex_dev_your_api_key_here"

Example response:

[
  {
    "id": "-OUB4DOcT-HrPKk8cUMc",
    "name": "Bjoriini",
    "description": "Grew up in a clan of blacksmiths...",
    "avatar_url": "https://...",
    "creation_date": 1752718963860,
    "tokenIndex": 0,
    "token_contract_address": "0x7ab7ea5408f1d2667138f73a32478e428ec4ef19",
    "creator_id": "0x5AD0806DaC04d629a275E188330A17fD70728C67"
  }
]

Get Agent Details

GET /v1/agents/{agentId}

Returns public details for a single agent.

curl "https://api.kex.gg/v1/agents/-OUB4DOcT-HrPKk8cUMc" \
  -H "Authorization: Bearer kex_dev_your_api_key_here"

Create Conversation

POST /v1/conversations

Creates an empty conversation with an agent.

Request body:

{
  "agentId": "string",
  "userId": "string"
}

Get Conversation History

GET /v1/conversations/{conversationId}

Retrieves the full message history for a conversation.

Send Message

POST /v1/messages

Sends a message to an agent. If no conversationId is provided, a new conversation is created. This costs 1 credit.

Request body:

{
  "agentId": "string",
  "userId": "string",
  "message": "string",
  "conversationId": "string" // optional
}

Text-to-Speech

POST /v1/tts

Generates speech using the agent's voice. Costs 3 credits per 100 characters (rounded up, minimum 1 credit).

Request body:

{
  "agentId": "string",
  "text": "string"
}

The response body is the raw audio/mpeg data.

WebSocket API

Connection URL: wss://ws.kex.gg

The WebSocket API is optimized for low-latency conversations.

Client Messages

All messages sent to the server must include a type field.

Start Conversation

{
  "type": "start_conversation",
  "agentId": "string",
  "userId": "string",
  "conversationId": "string" // optional
}

Send Message

{
  "type": "send_message",
  "conversationId": "string",
  "content": "string"
}

Server Messages

  • connected: sent after a successful connection.

  • conversation_started: confirms the conversation context.

  • agent_typing: the agent is preparing a response.

  • message: contains the agent's reply.

  • error: returned if something goes wrong.

Example agent response:

{
  "type": "message",
  "conversationId": "ws-conv-12345",
  "content": "Aye, I hear ye! ...",
  "messageId": "uuid-goes-here"
}

Error Codes

The API uses standard HTTP status codes:

  • 400 Bad Request

  • 401 Unauthorized

  • 402 Payment Required

  • 404 Not Found

  • 429 Too Many Requests

  • 500 Internal Server Error

Error responses include a JSON body with a human-readable message.

PreviousRewardsNextAgents

Last updated