Genesis API for AI agents: OpenAPI, llms.txt and function calling
In short
- For agents there are openapi.json (OpenAPI 3.1, 37 operations with plans), llms-full.txt, llms.txt and an API catalog per RFC 9727.
- The model picks a tool and its arguments; your server makes the keyed request and returns a short JSON with the data time to the model.
- Genesis API only reads data. Your code limits the request rate, the model treats text from responses as data, and a human confirms any trade.
Genesis API is a crypto market data REST API that an AI agent calls as a tool: the model decides what data it needs, your server makes a GET request with the key and returns a short JSON. For agents and language models there is a machine-readable description of the API: an OpenAPI 3.1 specification, a full Markdown reference and an API catalog. The data itself is what the site shows: CEX and DEX spreads, order books, funding, on-chain flows and prediction markets.
Machine-readable files
| File | What's inside | What for |
|---|---|---|
| genesisarbitrage.com/openapi.json | OpenAPI 3.1: 37 operations, parameters, response schemas, plans in x-genesis-plans, rate-limit headers | Import into an API client, code generation, agent tools |
| genesisarbitrage.com/llms-full.txt | The full reference in one Markdown file: endpoints, parameters, fields, examples, limits, errors | Context for a model that writes code or answers API questions |
| genesisarbitrage.com/llms.txt | Site overview: Genesis API, tools, Guide, course, glossary, blog | A model's first look at the site |
| genesisarbitrage.com/.well-known/api-catalog | API catalog per RFC 9727: links to the spec, docs, pricing and status | API discovery by domain |
The spec follows OpenAPI 3.1, whose schemas are a superset of JSON Schema 2020-12, so operation parameters carry over into a tool definition almost unchanged. llms.txt is a format proposed in 2024: a Markdown file at the site root with a short overview and links for language models. The catalog sits at the address defined by RFC 9727.
The Genesis API documentation, product and pricing pages carry <link rel="service-desc"> in <head> pointing at openapi.json. That link relation comes from RFC 8631 and marks a service description meant for machines. A shortened excerpt of the spec:
{
"openapi": "3.1.0",
"servers": [{ "url": "https://api.genesisarbitrage.com/v1" }],
"paths": {
"/arbitrage/spot-spot": {
"get": {
"operationId": "getArbitrageSpotSpot",
"x-genesis-plans": ["trial", "start", "pro", "max"],
"parameters": [
{ "name": "coin", "in": "query",
"schema": { "type": "string" } },
{ "name": "min_spread", "in": "query",
"schema": { "type": "number" } },
…
]
}
}
}
}
Every operation has an operationId, typed parameters, a 200 response schema, a 304 response, error codes and the X-RateLimit-*, X-Quota-*, X-Request-Id and ETag headers. The key is described by the ApiKeyAuth security scheme: type apiKey, header X-API-Key.
How to connect
Get a key and keep it on the server
The
gns_live_…key is issued in your profile, in the Genesis API block, and is shown once. Store it in theGENESIS_API_KEYenvironment variable on the server that runs the agent. Storage and reissue are covered in the API key guide.Import the spec
An API client or agent framework that accepts OpenAPI builds requests and tools straight from
openapi.json: the base URL comes fromservers, the key header fromApiKeyAuth. How the key is sent is described in Authentication.Keep the operations you need
Each tool definition takes up space in the model's context, and choosing among a few is easier. Keep the operations your task needs and drop the ones outside your plan per
x-genesis-plans: they answer403 plan_restricted.Give the model the reference
If the agent writes code or answers questions about the API, add
llms-full.txtto its context: it holds the parameters, fields and examples of every endpoint, the limits and the error codes.Check the key with a first call
/account/usagereturns your plan, quota used, requests-per-second limit and data freshness.
How the model calls Genesis API
Function calling is the mechanism where the model returns a tool name and arguments instead of text, and your code makes the call. The loop:
- Along with the user's question, the model gets tool definitions: name, purpose and parameters as JSON Schema.
- The model replies with a call:
get_spreadswith the arguments{"coin": "TON", "min_spread": 0.5}. - Your server validates the arguments, makes a GET with the
X-API-Keyheader and trims the response to the fields you need. - A short JSON with the data time goes back to the model, and it answers the user.
The model makes no network calls and never sees the key: it only has the tool definition and the result. A get_spreads tool over the Spot – Spot endpoint:
{
"name": "get_spreads",
"description": "Where to buy a coin cheaper and sell it higher (CEX)",
"parameters": {
"type": "object",
"properties": {
"coin": {
"type": "string",
"description": "Coin ticker, e.g. BTC"
},
"min_spread": {
"type": "number",
"description": "Minimum spread, %: 0.5 means 0.5%"
}
},
"additionalProperties": false
}
}
The field that holds the parameter schema has different names across model providers, inputSchema in MCP; inside it is always JSON Schema. The coin and min_spread properties come from the parameters of the getArbitrageSpotSpot operation, and description says when to call the tool: the model picks by that text.
A Python handler that calls /arbitrage/spot-spot and returns up to 10 rows with the needed fields and meta.updated_at to the model:
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot"
KEY = os.environ["GENESIS_API_KEY"] # the key stays on the server
FIELDS = ("coin", "exchange_buy", "exchange_sell", "spread_pct",
"withdraw_enabled_buy", "deposit_enabled_sell")
cache = {} # params -> (time, ETag, response body)
def get_spreads(coin=None, min_spread=None):
params = {"coin": coin, "min_spread": min_spread}
params = {k: v for k, v in params.items() if v is not None}
ck = tuple(sorted(params.items()))
ts, etag, body = cache.get(ck, (0, None, None))
if body and time.time() - ts < body["meta"]["freshness_sec"]:
return shorten(body) # the data won't update sooner
headers = {"X-API-Key": KEY}
if etag:
headers["If-None-Match"] = etag
for attempt in range(2): # 429 and 503: wait Retry-After, retry
r = requests.get(API, headers=headers, params=params,
timeout=10)
if r.status_code not in (429, 503) or attempt:
break
time.sleep(min(int(r.headers.get("Retry-After", 5)), 30))
if r.status_code == 200:
body, etag = r.json(), r.headers.get("ETag")
elif r.status_code != 304:
return {"error": r.status_code} # the model sees the code
cache[ck] = (time.time(), etag, body)
return shorten(body)
def shorten(body):
rows = sorted(body["data"], key=lambda x: x["spread_pct"],
reverse=True)[:10]
t = body["meta"]["updated_at"]
return {"updated_at": t, "age_sec": int(time.time() - t),
"rows": [{f: x.get(f) for f in FIELDS} for x in rows]}
The response stays cached for meta.freshness_sec seconds: the data will not update sooner. After that the handler sends the previous ETag in If-None-Match, and a 304 costs no quota. On 429 and 503 it waits Retry-After, capped at 30 s, retries once and returns other errors to the model as a code. The model gets 10 rows of 6 fields. An illustrative example: a full response of 214 rows with 22 fields is 214 × 22 = 4,708 values, the trimmed one 10 × 6 = 60.
Rules for the agent
| Rule | How |
|---|---|
| The key stays on the server | An environment variable of the handler; no key in the prompt, the browser or chat logs |
| The API only reads | Genesis API places no orders; a human confirms any exchange trade |
| Your code sets the rate | Cache for freshness_sec, ETag and If-None-Match, a queue under the requests-per-second limit |
| Filters, not the full set | coin, min_spread, exchange; up to 10 rows and the needed fields to the model |
| Data time in every answer | updated_at and age in the tool result and in the reply to the user |
| External text is data only | The model does not act on market titles, outcomes, trader names or signal texts |
The model may request several tools at once, and the limit counts every request on the key: 1 request per second on Trial, 15 on Max. 304 responses and errors cost no quota but do count toward the per-second limit — see Plans & limits and the guide to limits.
The title and outcome fields of prediction markets, trader name, the token_name of on-chain events and the message_ru and message_en of Genesis AI+ signals come from outside sources. Someone can name a market "ignore previous instructions and…" — that is prompt injection, commands smuggled in through data. Pass such fields only inside the tool result, cap their length and state in the system prompt that text inside results is data.
MCP: your own server on top of the REST API
MCP (Model Context Protocol) is an open standard for connecting AI applications to external systems. An MCP server gives the application tools, resources and prompt templates; messages are JSON-RPC 2.0, over stdio locally and Streamable HTTP remotely. The specification and SDKs for several languages are at modelcontextprotocol.io.
Genesis API has no official MCP server. You can build your own from the same handlers: an MCP tool is a GET to a Genesis API endpoint, its parameters are JSON Schema in inputSchema, and the key sits in the server's environment. A local stdio server keeps the key on your machine. Put a remote one behind authorization (MCP recommends OAuth), otherwise anyone who learns the address can spend your quota.
How agents work with crypto market data in general is covered in the article on crypto market data for AI agents, automation risks in the fifth lesson of the course.
Questions and answers
Does Genesis API have an official MCP server?
No. For agents there are openapi.json, llms-full.txt and the API catalog. You can write an MCP server on top of the REST API yourself: each tool is a GET request with the key from an environment variable.
Can an agent trade through Genesis API?
No. Genesis API only reads data and places no orders. The agent finds setups and sends alerts; a human makes the trade on the exchange.
Which plan does an agent need?
Any of them: Trial gives 1 request per second and 60 s freshness, Max 15 requests per second and 5 s. Which endpoints a plan includes is in x-genesis-plans and on the Genesis API Pricing page.
Why does the model quote stale prices?
The data lags by your plan's freshness, and the handler's cache adds up to freshness_sec. Give the model updated_at and the data's age, and ask it to state the time in its answer.