> ## Documentation Index
> Fetch the complete documentation index at: https://motiontrade.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://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:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: your_api_key_here" \
    "https://api.marketmotion.xyz/api/entities"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.marketmotion.xyz/api/entities', {
    headers: {
      'X-API-Key': 'your_api_key_here'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.marketmotion.xyz/api/entities',
      headers={'X-API-Key': 'your_api_key_here'}
  )
  ```

  ```bash CLI theme={null}
  motion auth login your_api_key_here
  motion entities search "Bitcoin"
  ```
</CodeGroup>

## Rate Limiting

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

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Cache responses locally">
    Entity data doesn't change frequently. Cache responses for 5-15 minutes to reduce API calls.
  </Accordion>

  <Accordion title="Use bulk endpoints">
    Fetch multiple entities at once using list endpoints with filters rather than individual lookups.
  </Accordion>

  <Accordion title="Implement exponential backoff">
    If rate limited, wait before retrying. Double the wait time on each retry.
  </Accordion>
</AccordionGroup>

## Error Responses

All errors follow a consistent format:

```json theme={null}
{
  "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

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

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