Genesis Arbitrage

Genesis Arbitrage · · 9 min read

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-Key header from your own server. Code reads it from the GENESIS_API_KEY environment 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 seeWhat it means
"Subscription inactive", "Subscribe" buttonNo API plan yet; the button opens the plans
"Subscription active", "Active until …", "Renew" buttonThe plan runs until that date
"Subscription expired", "Renew" buttonThe term is over: the key is rejected and the key buttons are hidden until you renew
"No key created yet", "Get key" buttonYou 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

  1. 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".

  2. Click "Get key"

    The button appears in the "Genesis API" block while you have no key. The key is created immediately.

  3. 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.

  4. Test the key with a request

    Call /account/usage as in the examples below. A 200 response with your plan in data.plan means 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.

PlaceOKWhy
Environment variable on the serverYesThe key stays out of code and the repository
A .env file listed in .gitignoreYesLoaded by python-dotenv (load_dotenv()) and by node --env-file=.env in Node.js 20.6+
Hosting and CI secretsYesThe platform hands the key to the program at start; in GitHub Actions, a repository secret passed through the step's env
Password managerYesA backup copy for a human
Request URLNoURLs end up in server and proxy logs and in browser history
Website, extension or mobile app codeNoAnyone who opens the page source or unpacks the app sees the key
Public repositoryNoThe key stays in commit history even after the file is deleted
Screenshots, chats, support ticketsNoMessages 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

ButtonWhat happensWhen to use it
"Reissue"The old key stops working at once, and the "Your API key" window shows a new oneThe 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" againYou 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:

  1. 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.

  2. Replace the key in every program

    Update environment variables, .env files 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 whether GENESIS_API_KEY is already set in the environment: python-dotenv and node --env-file do not overwrite a variable that is already set with the value from .env.

  3. Check your call usage

    The "Calls used" line in your profile or a request to /account/usage shows 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."
  }
}

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.