API Reference

Authentication

FromChain uses API keys to authenticate requests. All API requests must include your API key in the Authorization header.

API Keys

API keys are tenant-specific and can have different scopes and rate limits. Each key has a prefix for easy identification:

gw_live_...

Production API keys

gw_test_...

Test mode API keys

Making Authenticated Requests

Include your API key in the Authorization header using the Bearer scheme:

authenticated-request.js

const response = await fetch('https://api.fromchain.io/v1/invoices', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer gw_live_your_api_key_here',
    'Content-Type': 'application/json'
  }
});

if (!response.ok) {
  console.error('Authentication failed:', response.status);
}

const invoices = await response.json();
console.log(invoices);

API Key Management Endpoints

POST/v1/api-keys

Create a new API key for your tenant

create-api-key.js

const response = await fetch('https://api.fromchain.io/v1/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gw_live_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Production API Key',
    scopes: ['invoices:read', 'invoices:write', 'webhooks:manage'],
    rateLimitRpm: 100,
    expiresInDays: 365
  })
});

const apiKey = await response.json();
console.log('New API Key:', apiKey.key); // Save this immediately!

response.json

{
  "id": "key_abc123",
  "key": "gw_live_xyz789...",
  "keyPrefix": "gw_live_",
  "name": "Production API Key",
  "scopes": ["invoices:read", "invoices:write", "webhooks:manage"],
  "status": "ACTIVE",
  "createdAt": "2025-12-18T10:00:00Z"
}

GET/v1/api-keys

List all API keys for your tenant

PATCH/v1/api-keys/:id

Update an API key (change name, scopes, or rate limits)

DELETE/v1/api-keys/:id/revoke

Revoke an API key immediately

Permission Scopes

API keys can have granular permissions. Here are the available scopes:

invoices:read

Read access to invoices (GET /v1/invoices, GET /v1/invoices/:id)

invoices:write

Create invoices (POST /v1/invoices)

webhooks:manage

Full access to webhook endpoints (create, update, delete)

withdrawals:write

Create withdrawal requests (POST /v1/withdrawals)

admin

Full administrative access to all resources

Rate Limiting

Each API key has a rate limit measured in requests per minute (RPM). When you exceed your limit, you'll receive a 429 response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1702905600

{
  "statusCode": 429,
  "message": "Rate limit exceeded. Try again in 45 seconds.",
  "error": "Too Many Requests"
}

💡 Tip: Check the X-RateLimit-* headers to monitor your usage and implement backoff strategies.

Security Best Practices

Store keys securely

Never commit API keys to version control. Use environment variables or secret management systems.

Use minimal scopes

Create API keys with only the scopes they need. Don't use 'admin' scope unless absolutely necessary.

Rotate keys regularly

Set expiration dates and rotate keys periodically for enhanced security.

Use HTTPS only

Always make API requests over HTTPS to prevent key interception.