Genesis API key: how to get it, where to store it, how to reissue and revoke it
In short
- A
gns_live_…key is created in your profile with the "Get key" button and shown only once. We store only its hash, so a lost key cannot be recovered, only reissued. - The key goes in the
X-API-Keyheader from your own server. Code reads it from theGENESIS_API_KEYenvironment variable; it never goes into a request URL or website code. - If the key leaks, click "Reissue": the old key stops working at once, and you replace it in every program. Each account gets one key.
An API key for Genesis API is a gns_live_… string that works like a password: the server uses it to identify your account and plan. You send it with every request in the X-API-Key HTTP header; without a key, or with a wrong one, the API returns 401 invalid_key. Each account gets one key, and you get, reissue and revoke it in your Genesis Arbitrage profile.
Where the key lives
You manage the key in your profile, in the "Genesis API" block; the other profile blocks are covered in the account profile guide. The block shows your API subscription and the state of the key:
| What you see | What it means |
|---|---|
| "Subscription inactive", "Subscribe" button | No API plan yet; the button opens the plans |
| "Subscription active", "Active until …", "Renew" button | The plan runs until that date |
| "Subscription expired", "Renew" button | The term is over: the key is rejected and the key buttons are hidden until you renew |
| "No key created yet", "Get key" button | You have a plan but no key yet |
"API key" and gns_live_… | The start of the active key; the full key is never shown again |
| "created …" · "used …" | When the key was created and when it last made a request |
| "Calls used", "req/s", "freshness", "resets …" | Quota used, requests-per-second limit, data delay and the date the counter resets |
The "Documentation" link in the corner of the block opens the Genesis API documentation. Quota and limits are explained in the guide to Genesis API limits.
How to get a key
Subscribe to an API plan
On the Genesis API Pricing page, choose Trial, Start, Pro or Max and a period, click "Subscribe" and pay the invoice in crypto. The status in your profile changes to "Subscription active".
Click "Get key"
The button appears in the "Genesis API" block while you have no key. The key is created immediately.
Save the key from the "Your API key" window
The window shows the full key once. Click "Copy" and put the key in a password manager or straight into your server's protected variables. After "Done" you cannot see the full key again: we keep only its hash.
Test the key with a request
Call
/account/usageas in the examples below. A200response with your plan indata.planmeans the key is accepted.
How to send the key
The key goes only in the X-API-Key header. The server does not read a key from URL parameters or from the Authorization header and answers 401. The examples read the key from the GENESIS_API_KEY environment variable; the base URL is https://api.genesisarbitrage.com/v1.
curl:
# the key comes from an environment variable
curl "https://api.genesisarbitrage.com/v1/account/usage" \
-H "X-API-Key: $GENESIS_API_KEY"
Python 3.10+ with the requests library:
import os
import requests
# os.environ[...] fails right away if the variable is not set
key = os.environ["GENESIS_API_KEY"]
r = requests.get(
"https://api.genesisarbitrage.com/v1/account/usage",
headers={"X-API-Key": key},
timeout=10,
)
r.raise_for_status()
print(r.json()["data"]["plan"])
JavaScript, Node.js 18+ with the built-in fetch:
// .mjs file: modules allow top-level await
const key = process.env.GENESIS_API_KEY;
if (!key) throw new Error('GENESIS_API_KEY is not set');
const res = await fetch(
'https://api.genesisarbitrage.com/v1/account/usage',
{ headers: { 'X-API-Key': key } },
);
const body = await res.json();
console.log(res.status, body.data?.plan);
All three requests return the same response (illustrative values):
{
"success": true,
"data": {
"plan": "pro",
"calls_used": 184201,
"calls_limit": 5000000,
"rps_limit": 5,
"freshness_sec": 10,
"period_resets_at": 1786492800
},
"meta": { … }
}
The response fields are described in the Usage section of the documentation.
Where to store the key
A Genesis API key only reads data: you cannot trade or withdraw funds with it. A leak costs you something else: other people's programs burn through your quota and your requests-per-second limit.
| Place | OK | Why |
|---|---|---|
| Environment variable on the server | Yes | The key stays out of code and the repository |
A .env file listed in .gitignore | Yes | Loaded by python-dotenv (load_dotenv()) and by node --env-file=.env in Node.js 20.6+ |
| Hosting and CI secrets | Yes | The platform hands the key to the program at start; in GitHub Actions, a repository secret passed through the step's env |
| Password manager | Yes | A backup copy for a human |
| Request URL | No | URLs end up in server and proxy logs and in browser history |
| Website, extension or mobile app code | No | Anyone who opens the page source or unpacks the app sees the key |
| Public repository | No | The key stays in commit history even after the file is deleted |
| Screenshots, chats, support tickets | No | Messages and images get forwarded |
If the data has to reach a browser, such as a dashboard or an extension, your server calls Genesis API and the browser gets the finished result from your server. Support needs the X-Request-Id from the response, the request time in UTC, the endpoint and the status, never the key. Exchange keys with trading rights are riskier; how to restrict them is covered in how to secure your crypto exchange account.
Reissuing and revoking
| Button | What happens | When to use it |
|---|---|---|
| "Reissue" | The old key stops working at once, and the "Your API key" window shows a new one | The key leaked or was lost, or someone who had it has left |
| "Revoke" | The key is switched off without a replacement and API access is closed; the block shows "Get key" again | You no longer need the key |
Both buttons ask for confirmation first. The dialogs read "Reissue the key? The current key stops working immediately." and "Revoke the key? It stops working at once and API access is closed." and offer "Cancel" and "Confirm". If the key leaked:
Reissue the key
Click "Reissue", then "Confirm", and save the new key from the "Your API key" window. From that moment requests with the old key get
401.Replace the key in every program
Update environment variables,
.envfiles and CI and hosting secrets, then restart the programs: a process reads its environment at start. If a program still sends the old key, check whetherGENESIS_API_KEYis already set in the environment: python-dotenv andnode --env-filedo not overwrite a variable that is already set with the value from.env.Check your call usage
The "Calls used" line in your profile or a request to
/account/usageshows how many calls were spent this period. Reissuing does not reset the counter.
401 invalid_key: what to check
The server answers 401 with the invalid_key code when the key is missing, wrong or revoked, or the subscription has expired:
{
"success": false,
"error": {
"code": "invalid_key",
"message": "Missing X-API-Key header."
}
}
- The header did not arrive. "Missing X-API-Key header." means the request carried no key at all. Check the header name and whether the variable is set where the program runs: on the server, in the container, in the scheduled job.
- The key is mangled. An extra space, quotes inside the value or a cut-off end give
401: the key has to match character for character. - The key was reissued or revoked. Compare the start of the key in your program with the start your profile shows under "API key".
- The subscription expired. Your profile shows "Subscription expired". After "Renew" the same key works again, with no need to reissue it.
If the header arrived but the key was rejected, message lists all the possible reasons at once. A 403 plan_restricted response means something else: the key is accepted, but the endpoint is not part of your plan. Other codes are in the Errors section and in the guide to Genesis API responses and errors.
The "Try it" form in the documentation
Every endpoint in the documentation has a "Try it" form. Paste the key into the "Your API key (gns_live_…)" field and click "Send request": the status code, the response time and a truncated response appear below the form. The key is stored only in your browser and is sent nowhere except the API.
The browser remembers the key and fills in the field on your next visit, so do not use the form on someone else's computer. A request from the form is a regular API call: it uses the quota and the requests-per-second limit just like a request from code. Your first request from code, with the response explained, is in Genesis API quick start.
Questions and answers
Can I have a separate key for each bot?
No, each account gets one key. Every program using it shares the call quota and the requests-per-second limit. If the limits are too tight, upgrade your plan: opening several accounts to get around limits breaks the rules.
Does reissuing reset the call counter?
No. "Calls used" belongs to the account's subscription, not to the key: the new key continues the same 30-day period.
Can I write the header in lowercase, x-api-key?
Yes. HTTP header names are case-insensitive, a rule set by RFC 9110, section 5.1. The key itself must be sent unchanged.
Do I need a new key after renewing?
No. While the subscription is expired the key gets 401, and after "Renew" the same key works again.