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
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
Authorization header determines which Solana network is used.
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:
curl https://api.zendfi.tech/api/v1/payments \
-H "Authorization: Bearer zfi_test_your_key"
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.
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"}'
idempotencyEnabled is true (the default).
The CLI also sends idempotency keys for write requests and supports explicit keys on core payment/intent commands.
All errors follow a consistent structure:
{
"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 |
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709312400
429 with a JSON body indicating when to retry.
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 |
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
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 |
Sub-Account Programmable Controls
ZendFi sub-accounts now include programmable controls for policy enforcement, execution gating, reactive triggers, and balance automation.
