API Keys

API keys provide programmatic access to the Nexgent API, primarily for creating trading signals from external systems.

Overview

Feature	Description
Format	`nex_<32_random_characters>`
Storage	SHA-256 hash (raw key shown once)
Scopes	`full_access`, `signals`, `agents`, `positions`, `balances`, `transactions`, `history`
Expiration	Never (until deleted)

Key Format

nex_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

└─┬─┘└────────────┬────────────────┘
prefix     32 random characters

⚠️

The raw API key is shown only once when created. Store it securely - it cannot be retrieved later.

Using API Keys

X-API-Key Header (Recommended)

curl -X POST https://your-instance.com/api/v1/trading-signals \
  -H "X-API-Key: nex_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{"tokenAddress": "...", "action": "buy", "score": 4}'

Bearer Token Format

API keys also work as Bearer tokens:

curl -X POST https://your-instance.com/api/v1/trading-signals \
  -H "Authorization: Bearer nex_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{"tokenAddress": "...", "action": "buy", "score": 4}'

Scopes

API keys have scoped permissions:

Scope	Description	Endpoints
`full_access`	Full API access (all permissions)	All endpoints
`signals`	Read & write trading signals	`GET/POST /trading-signals`
`agents`	Read agent data & configuration	`GET /agents`
`positions`	Read open positions	`GET /agent-positions`
`balances`	Read agent balances	`GET /agent-balances`
`transactions`	Read transaction history	`GET /agent-transactions`
`history`	Read historical swaps	`GET /agent-historical-swaps`

Use Full Access for complete API access, or select specific scopes in Restricted mode for minimal permissions.

Managing API Keys

Create API Key

POST /api/v1/api-keys
Authorization: Bearer <jwt_access_token>
Content-Type: application/json
 
{
  "name": "Trading Bot",
  "scopes": ["signals"]
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Trading Bot",
  "key": "nex_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "prefix": "nex_a1b2",
  "scopes": ["signals"],
  "createdAt": "2024-01-15T10:30:00.000Z"
}

🚫

Save the key value immediately! This is the only time it will be shown.

List API Keys

GET /api/v1/api-keys
Authorization: Bearer <jwt_access_token>

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Trading Bot",
    "prefix": "nex_a1b2",
    "scopes": ["signals"],
    "lastUsedAt": "2024-01-15T12:00:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
]

Delete API Key

DELETE /api/v1/api-keys/:id
Authorization: Bearer <jwt_access_token>

Response:

{
  "success": true
}

Security

Key Storage

Raw key is never stored - only the SHA-256 hash
Key cannot be recovered if lost
Prefix (nex_a1b2) stored for identification

Verification Process

Extract key from X-API-Key or Authorization header
Compute SHA-256 hash of provided key
Compare hash with stored hash (timing-safe)
Verify key belongs to active user
Check required scope permissions

Best Practices

Do	Don't
Store keys in environment variables	Commit keys to git
Use minimal required scopes	Give unnecessary permissions
Rotate keys periodically	Share keys between services
Delete unused keys	Keep old keys active
Use separate keys per integration	Reuse keys across environments

Errors

Status	Error	Cause
401	`API key required`	No key in header
401	`Invalid API key`	Key not found or wrong hash
403	`API key missing required scope: signals`	Key lacks required permission

JWT Tokens Login & Registration