Skip to main content

​
API Keys

All Matchr API requests require authentication using an API key.

​
Getting Your API Key

1

Sign In

Log in to your Matchr account at matchr.xyz.
2

Navigate to Settings

Go to Settings → API Keys.
3

Create Key

Click Create API Key, give it a name, and click Generate.
4

Copy Key

Copy your API key immediately. It will only be shown once.
Store your API key securely. If you lose it, you’ll need to generate a new one.

​
Using Your API Key

​
Bearer Token Authentication

Include your API key in the Authorization header: 
curl -X GET "https://api.matchr.xyz/v1/events" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
SDK Authentication

import { Matchr } from '@matchr/sdk';

const matchr = new Matchr({
  apiKey: process.env.MATCHR_API_KEY
});

from matchr import MatchrClient

client = MatchrClient(api_key=os.environ["MATCHR_API_KEY"])

​
Key Types

TypePermissionsUse Case
Read-OnlyMarket data, prices, matchesAnalytics, dashboards
TradingAll read + order placementTrading bots
AdminAll permissionsFull API access

​
Security Best Practices

API keys should only be used server-side. Never include them in client-side JavaScript.
// ❌ Bad: Exposed in browser
const apiKey = 'sk_live_abc123';

// ✅ Good: Server-side only
const apiKey = process.env.MATCHR_API_KEY;
Store keys in environment variables, not in code.
# .env
MATCHR_API_KEY=sk_live_abc123
Generate new keys periodically and revoke old ones.
Create read-only keys for analytics. Only use trading keys when needed.

​
Error Handling

​
Unauthorized (401)

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
Causes:
  • Missing Authorization header
  • Invalid API key
  • Revoked API key

​
Forbidden (403)

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions for this action"
  }
}
Causes:
  • Read-only key attempting trading endpoint
  • Account restrictions

​
Key Management

​
View Active Keys

See all your API keys in Settings → API Keys.

​
Revoke a Key

Click Revoke next to any key to immediately disable it.

​
Rename a Key

Click the key name to edit it for better organization.

​
Rate Limiting by Key

Each API key has its own rate limit:
TierKeys AllowedRate Limit/Key
Free260/min
Pro10300/min
EnterpriseUnlimitedCustom

​
Next Steps

Get Events

Start fetching market data.

Place Orders

Execute trades via API.