Authentication

API keys and rate limits

No Key Required

Most Market Motion endpoints work without authentication. This lets you explore the API and prototype quickly.

Anonymous rate limit: 30 requests/minute

API Keys

For production use, get an API key to increase your rate limits.

Getting a Key

1. Visit marketmotion.xyz/developer
2. Sign in with your account
3. Click “Create API Key”
4. Choose key type (Test or Live)

Key Types

Type	Rate Limit	Use Case
Test Key	100 req/min	Development and testing
Live Key	300 req/min	Production applications

Using Your Key

Include the API key in the X-API-Key header:

cURL

curl -H "X-API-Key: your_api_key_here" \
  "https://api.marketmotion.xyz/api/entities"

Rate Limiting

When you exceed your rate limit, you’ll receive a 429 response:

{
  "success": false,
  "error": "Rate limit exceeded. Please try again later."
}

Rate Limit Headers

Every response includes rate limit information:

Header	Description
X-RateLimit-Limit	Your requests per minute limit
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when limit resets

Best Practices

Cache responses locally

Entity data doesn’t change frequently. Cache responses for 5-15 minutes to reduce API calls.

Use bulk endpoints

Fetch multiple entities at once using list endpoints with filters rather than individual lookups.

Implement exponential backoff

If rate limited, wait before retrying. Double the wait time on each retry.

Error Responses

All errors follow a consistent format:

{
  "success": false,
  "error": "Description of what went wrong"
}

HTTP Status Codes

Code	Meaning
200	Success
400	Bad request (invalid parameters)
401	Invalid API key
404	Entity or market not found
429	Rate limit exceeded
500	Server error

Security

Keep your API keys secret. Never commit them to version control or expose them in client-side code.

Best practices:

• Store keys in environment variables
• Use server-side code to make API calls
• Rotate keys if compromised
• Use Test keys for development, Live keys for production