SURCHI API Authentication: API Keys and Bearer Tokens

Every request to the SURCHI API must be authenticated with an API key passed as a Bearer token in the Authorization header. API keys are tied to your account, carry specific permission scopes, and are the primary mechanism for tracking and enforcing your plan’s rate limits. There are no public endpoints — even read-only queries require a valid key.

Getting an API Key

Go to surchi.xyz/dashboard and sign in with your account credentials.

Navigate to API Keys

Open the left sidebar and click Settings, then select API Keys from the settings menu.

Click "Create New Key"

Click the Create New Key button in the top-right corner of the API Keys page.

Name your key and choose its scope

Give the key a descriptive name (e.g. prod-trading-bot or dev-portfolio-app) so you can identify it later. Select the minimum set of scopes your application needs. See the Key Scopes table below for available options.

Copy the key immediately

After creation, your full API key is displayed exactly once. Copy it now and store it in a secure secrets manager or environment variable. If you lose it, you will need to revoke the key and create a new one.

Using Your API Key

Pass your API key in the Authorization header using the Bearer scheme on every request. The header must be formatted exactly as shown — including the Bearer prefix followed by a single space.

Authorization: Bearer sk_live_xxxxxxxxxxxx

curl -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  https://api.surchi.xyz/v1/trending

const SURCHI_API_KEY = process.env.SURCHI_API_KEY;

const headers = {
  'Authorization': `Bearer ${SURCHI_API_KEY}`,
  'Content-Type': 'application/json'
};

const response = await fetch('https://api.surchi.xyz/v1/trending', { headers });
const data = await response.json();

import os
import requests

headers = {
    'Authorization': f'Bearer {os.environ["SURCHI_API_KEY"]}',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.surchi.xyz/v1/trending', headers=headers)
print(response.json())

import (
    "net/http"
    "os"
)

req, _ := http.NewRequest("GET", "https://api.surchi.xyz/v1/trending", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SURCHI_API_KEY"))
req.Header.Set("Content-Type", "application/json")

client := &http.Client{}
resp, err := client.Do(req)

use reqwest::Client;

let api_key = std::env::var("SURCHI_API_KEY").expect("SURCHI_API_KEY not set");
let client = Client::new();

let response = client
    .get("https://api.surchi.xyz/v1/trending")
    .header("Authorization", format!("Bearer {}", api_key))
    .send()
    .await?;

Key Scopes

When you create an API key, you assign it one or more scopes that define what it is allowed to do. Use the narrowest set of scopes your application actually requires — this limits the blast radius if a key is ever exposed.

Scope	Description
`read:tokens`	Read token data and analytics
`read:wallets`	Read wallet data and PnL
`read:contracts`	Run AI contract audits
`read:liquidity`	Access liquidity and routing data
`write:alerts`	Create and manage alerts
`full`	All permissions (use with caution)

For most read-only integrations, you only need read:tokens and read:wallets. Avoid the full scope unless your application genuinely requires write access alongside all read permissions.

Key Rotation

You should rotate your API keys periodically and immediately after any suspected exposure. To rotate a key:

Create a new key with the same scopes as the one you are replacing.
Deploy the new key to your application and verify it works correctly.
Revoke the old key from the Settings → API Keys dashboard.

Revoking a key takes effect immediately and is irreversible. Any application still using the old key will begin receiving 401 Unauthorized errors the moment you revoke it. Always confirm your new key is fully deployed and operational before revoking the old one.

Security Best Practices

Keeping your API keys secure is your responsibility. Follow these practices to minimise risk:

Use environment variables. Never hard-code API keys in your source code. Load them at runtime from environment variables or a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or Doppler.
Never commit keys to source control. Add a .env file (or whichever file holds your secrets) to .gitignore. Scan your repository history if you suspect a key was ever committed, and rotate it immediately.
Use narrow scopes. Issue separate keys for separate applications, each with only the scopes it needs. A compromised read-only key cannot be used to create or destroy alerts.
Monitor key usage. The SURCHI dashboard shows per-key request volume and error rates. Unusual spikes may indicate your key has been shared or leaked.
Rotate keys regularly. Even without a known incident, rotating keys every 90 days is a sound practice for production applications.

Authentication Errors

If your key is missing, malformed, or has been revoked, the API returns HTTP 401. If your key is valid but lacks the required scope for the endpoint you called, it returns HTTP 403.

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "status": 401
  }
}

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Your API key does not have the required scope for this endpoint",
    "status": 403
  }
}

See the Errors reference for the full list of error codes and troubleshooting guidance.

API Reference

SDK

Webhooks

SURCHI API Authentication: API Keys and Bearer Tokens

Getting an API Key

Using Your API Key

Key Scopes

Key Rotation

Security Best Practices

Authentication Errors

​Getting an API Key

​Using Your API Key

​Key Scopes

​Key Rotation

​Security Best Practices

​Authentication Errors

Getting an API Key

Using Your API Key

Key Scopes

Key Rotation

Security Best Practices

Authentication Errors