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

# Authentication

> API keys, rate limits, and security

# Authentication

All Zet API requests require authentication via an API key sent in the request header.

## API Key

Include your API key in every request using the `x-api-key` header:

```bash theme={null}
curl https://api.zet.money/v1/wallets \
  -H "x-api-key: zet_live_your_api_key"
```

### Key types

| Key Type | Prefix      | Purpose                                  |
| -------- | ----------- | ---------------------------------------- |
| **Live** | `zet_live_` | Production transactions with real funds  |
| **Test** | `zet_test_` | Staging environment, no real funds moved |

### Key management

* Contact [zetdotmoney@gmail.com](mailto:zetdotmoney@gmail.com) to generate or revoke keys
* Each API key is scoped to your organization
* You can have multiple active keys (e.g., one per environment)
* Revoking a key takes effect immediately

<Warning>
  **Keep your API key secret.** Never expose it in client-side code, public repositories, or frontend applications. All API calls must be made from your backend server.
</Warning>

## API Secret

When you generate an API key, you also receive an **API Secret** (`zet_secret_...`). This is used exclusively for **webhook signature verification**.

```
x-zet-signature: <HMAC-SHA256 hash of the request body using your API secret>
```

See the [Webhooks guide](/guides/webhooks) for verification implementation.

<Info>
  The API secret is shown only once when you create the key. If you lose it, revoke the key and create a new one.
</Info>

## Rate Limits

| Plan           | Rate Limit       | Burst           |
| -------------- | ---------------- | --------------- |
| **Free**       | 60 requests/min  | 10 requests/sec |
| **Growth**     | 300 requests/min | 50 requests/sec |
| **Enterprise** | Custom           | Custom          |

Rate limit information is included in every response:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1709384400
```

When rate limited, you'll receive a `429` response:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 45 seconds."
  }
}
```

### Best practices

* Implement exponential backoff on `429` responses
* Cache quote responses locally until they expire
* Use webhooks instead of polling for transaction status
* Batch wallet balance checks when possible

## Request format

All requests use JSON:

```
Content-Type: application/json
```

## Response format

Every response follows a consistent envelope:

**Success:**

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

**Success with pagination:**

```json theme={null}
{
  "success": true,
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  }
}
```

**Error:**

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The 'amount' field must be a positive number."
  }
}
```

## IP allowlisting

For additional security, you can restrict API key usage to specific IP addresses. Contact [zetdotmoney@gmail.com](mailto:zetdotmoney@gmail.com) to configure IP allowlisting for your production keys.

## HTTPS only

All API requests must be made over HTTPS. Requests over HTTP will be rejected.