API Keys

If you haven't already, sign up and go through our official onboarding for a full suite of tutorials, including getting API keys and starting your AI research agent. Keep reading for a more in-depth explanation about our API and MCP.

Create an API Key

1. Sign in and open Account Settings.
2. Scroll to Automation and select Create API Key.
3. Give the key a name that identifies the integration using it.
4. Select only the scopes the integration needs.
5. Confirm with your password and MFA code, if enabled.
6. Copy the Public ID and Secret Key. The Secret Key is shown only once.

Use a separate key for each integration. If a key is lost or exposed, open View API Keys, revoke it, and create a replacement.

Scopes

Scope	Allows
Update account and model profile information	Editing account and model profiles
Upload submissions and pickled models	Uploading predictions and models, and configuring submission webhooks
Download previous submissions and pickled models	Downloading your prior submissions and uploaded models
Make stakes	Managing legacy tournament stakes
Manage web3 staking	Managing atomic blockchain stakes
View historical submission info	Reading private submission history
View user info	Reading private account details, balances, withdrawals, and model IDs
Ability to delete your models and your account	Deleting models or the account

WARNING

Follow the principle of least privilege. In particular, do not grant staking or deletion scopes to submission automation.

Storing Credentials

Do not put credentials directly in source code or commit them to a repository. For deployed workloads, use the secret manager provided by your hosting or CI platform. If you use a local .env file, add it to .gitignore and restrict its file permissions.

NumerAPI reads the NUMERAI_PUBLIC_ID and NUMERAI_SECRET_KEY environment variables automatically.

macOS and Linux

export NUMERAI_PUBLIC_ID="YOUR_PUBLIC_ID"
export NUMERAI_SECRET_KEY="YOUR_SECRET_KEY"

Windows PowerShell

$env:NUMERAI_PUBLIC_ID = "YOUR_PUBLIC_ID"
$env:NUMERAI_SECRET_KEY = "YOUR_SECRET_KEY"

Numerai MCP

Numerai MCP connects supported AI agents to Numerai tools for tournament information and research assistance.

Supported AI Agents

• Codex CLI (recommended)
• Cursor
• Claude Code

Authenticate

Numerai MCP uses a Numerai API key. From the Automation section of Account Settings, select Create MCP Key to create a key with the scopes needed for full MCP functionality:

• Upload submissions and pickled models
• Download previous submissions and pickled models
• View historical submission info
• View user info, such as balances and withdrawal history

You can also use an existing API key if it has these scopes.

Set NUMERAI_MCP_AUTH to the key's Public ID and Secret Key in the following format:

export NUMERAI_MCP_AUTH="Token PUBLIC_ID\$SECRET_KEY"

WARNING

The $ between the Public ID and Secret Key must be escaped in many shells, as shown above.

Install

Codex CLI

The one-line installer guides you through creating an MCP key in the Numerai web app and configuring the environment variable:

curl -sL https://numer.ai/install-mcp.sh | bash

To install it manually, add the following configuration to ~/.codex/config.toml:

[mcp_servers.numerai]
url = "https://api-tournament.numer.ai/mcp/sse"

[mcp_servers.numerai.env_http_headers]
Authorization = "NUMERAI_MCP_AUTH"

Cursor

Add the following configuration to the mcpServers object in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "numerai": {
      "url": "https://api-tournament.numer.ai/mcp/sse",
      "headers": {
        "Authorization": "${env:NUMERAI_MCP_AUTH}"
      }
    }
  }
}

Claude Code

Export NUMERAI_MCP_AUTH before running this command so the authentication header is included:

claude mcp add --transport http numerai https://api-tournament.numer.ai/mcp --header "Authorization: ${NUMERAI_MCP_AUTH}"

Use MCP

After installation, your agent should connect to Numerai MCP automatically on startup. You can ask it in natural language to use tools in two main categories:

• Tournament information, such as leaderboards, model performance, and the current round
• Research assistance, such as creating and uploading models or checking submissions

Numerai MCP also provides a generic GraphQL tool that lets an agent inspect the schema, build GraphQL requests, and execute them.

NumerAPI

NumerAPI is the official Python client and lightweight command-line interface for the Numerai API. Install or upgrade it with:

python -m pip install --upgrade numerapi

Once the environment variables above are set, NumerAPI loads them automatically:

from numerapi import NumerAPI

napi = NumerAPI()
models = napi.get_models()
print(models)

Use SignalsAPI for Numerai Signals and CryptoAPI for Numerai Crypto:

from numerapi import CryptoAPI, SignalsAPI

signals_api = SignalsAPI()
crypto_api = CryptoAPI()

The package also installs a numerapi command. For example:

numerapi models
numerapi current-round
numerapi --help

See the NumerAPI reference for all Python methods and commands.

GraphQL API

Applications in other languages can call the GraphQL API directly. Send the two key parts in the Authorization header, separated by a literal $:

Authorization: Token PUBLIC_ID$SECRET_KEY

For example, after setting the environment variables above:

NUMERAI_API_TOKEN="${NUMERAI_PUBLIC_ID}\$${NUMERAI_SECRET_KEY}"

curl https://api-tournament.numer.ai/ \
  --header "Authorization: Token ${NUMERAI_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"query":"query { account { username } }"}'

The selected scopes must authorize every protected field or mutation in the request.

Troubleshooting

• The Secret Key is missing: it cannot be displayed again. Revoke the key and create a replacement.
• An operation is unauthorized: confirm both key parts are present and that the key has the required scope. Scopes cannot be added to an existing key; create a correctly scoped replacement.
• Numerai MCP cannot authenticate: confirm NUMERAI_MCP_AUTH is exported in the environment that starts the agent and includes the literal $ separator.
• A key may have leaked: revoke it immediately, rotate the credentials wherever they are used, and review the integration's logs.