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

# API Overview

> Base URL, versioning, request format, error handling, and pagination for the ZendFi API.

# API Overview

The ZendFi API is a REST API that accepts JSON request bodies and returns JSON responses. All endpoints are versioned under `/api/v1/`.

## Base URL

```
https://api.zendfi.tech/api/v1
```

Both test and live modes share the same base URL. The API key in your `Authorization` header determines which Solana network is used.

## Request Format

All requests must include:

| Header            | Value                                          | Required                        |
| ----------------- | ---------------------------------------------- | ------------------------------- |
| `Authorization`   | `Bearer zfi_test_...` or `Bearer zfi_live_...` | Yes (protected routes)          |
| `Content-Type`    | `application/json`                             | Yes (POST/PUT/PATCH)            |
| `Idempotency-Key` | UUID or unique string                          | Optional (recommended for POST) |

## Authentication

Protected endpoints require a valid API key as a Bearer token:

```bash theme={null}
curl https://api.zendfi.tech/api/v1/payments \
  -H "Authorization: Bearer zfi_test_your_key"
```

See [Authentication](/authentication) for details on key formats and management.

## Idempotency

For write operations (`POST`, `PUT`, `PATCH`), include an `Idempotency-Key` header to make retries safe.

* The key is scoped per merchant and endpoint.
* Repeating the same key with the same request payload returns the original response.
* Reusing the same key with a different payload returns `409` conflict.
* If an identical request with the same key is still processing, the API can return `409` in-flight conflict (`idempotency_in_flight`).
* Stored idempotency records expire after 24 hours.

```bash theme={null}
curl -X POST https://api.zendfi.tech/api/v1/payments \
  -H "Authorization: Bearer zfi_test_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345_payment" \
  -d '{"amount": 50, "currency": "USD"}'
```

The SDK generates idempotency keys automatically when `idempotencyEnabled` is `true` (the default).
The CLI also sends idempotency keys for write requests and supports explicit keys on core payment/intent commands.

## Error Format

All errors follow a consistent structure:

```json theme={null}
{
  "error": "Human-readable error message",
  "code": "machine_readable_error_code",
  "details": {}
}
```

### HTTP Status Codes

| Code  | Meaning                                                     |
| ----- | ----------------------------------------------------------- |
| `200` | Success                                                     |
| `201` | Resource created                                            |
| `400` | Bad request -- invalid parameters                           |
| `401` | Unauthorized -- invalid or missing API key                  |
| `404` | Resource not found                                          |
| `409` | Conflict -- resource already exists or idempotency conflict |
| `422` | Unprocessable entity -- validation error                    |
| `429` | Rate limit exceeded                                         |
| `500` | Internal server error                                       |

### Common Error Codes

| Code                     | Description                      |
| ------------------------ | -------------------------------- |
| `authentication_failed`  | Invalid or expired API key       |
| `validation_failed`      | Request body failed validation   |
| `missing_required_field` | A required field is missing      |
| `invalid_parameter`      | A parameter has an invalid value |
| `rate_limit_exceeded`    | Too many requests                |
| `payment_expired`        | Payment window has elapsed       |
| `insufficient_balance`   | Wallet balance too low           |

## Rate Limits

Requests are rate-limited per merchant account:

| Category            | Limit        | Window |
| ------------------- | ------------ | ------ |
| Payment endpoints   | 50 requests  | 1 hour |
| Dashboard endpoints | 200 requests | 1 hour |
| All other endpoints | 100 requests | 1 hour |

Rate limit information is included in response headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709312400
```

When the limit is exceeded, the API returns `429` with a JSON body indicating when to retry.

## Pagination

List endpoints support pagination via query parameters:

| Parameter | Type    | Default | Description                        |
| --------- | ------- | ------- | ---------------------------------- |
| `limit`   | integer | 20      | Number of items per page (max 100) |
| `offset`  | integer | 0       | Number of items to skip            |

```bash theme={null}
curl "https://api.zendfi.tech/api/v1/payments?limit=10&offset=20" \
  -H "Authorization: Bearer zfi_test_your_key"
```

## Correlation IDs

Every API request is assigned a unique correlation ID, available in the response headers:

```
X-Correlation-Id: 550e8400-e29b-41d4-a716-446655440000
```

Include this ID when contacting support to help trace issues quickly.

## Mode Header

Every response includes a header indicating which mode processed the request:

```
X-ZendFi-Mode: test
```

This helps verify that your application is hitting the expected network (devnet or mainnet).

## Supported Currencies and Tokens

| Currency | Description         |
| -------- | ------------------- |
| `USD`    | US Dollar (default) |
| `EUR`    | Euro                |
| `GBP`    | British Pound       |

| Token  | Network             |
| ------ | ------------------- |
| `USDC` | SPL Token (default) |
| `USDT` | SPL Token           |
| `SOL`  | Native SOL          |

## Related API References

* [Payments](/api-reference/payments)
* [Refunds](/api-reference/refunds)
* [Disputes](/api-reference/disputes)
* [Webhooks](/api-reference/webhooks)
* [Fraud Controls](/api-reference/fraud-controls)
* [Sub Accounts](/api-reference/sub-accounts)

## Sub-Account Programmable Controls

ZendFi sub-accounts now include programmable controls for policy enforcement, execution gating, reactive triggers, and balance automation.

* [Sub-Accounts Overview](/api-reference/sub-accounts)
* [Create Policy Version](/api-reference/sub-accounts#create-policy-version)
* [Create Execution Intent](/api-reference/sub-accounts#create-execution-intent)
* [Create Webhook Trigger Subscription](/api-reference/sub-accounts#create-webhook-trigger-subscription)
* [Create Balance Rule](/api-reference/sub-accounts#create-balance-rule)