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

# API Introduction

> Welcome to the XentFi API Reference. This documentation provides detailed information about all available endpoints, request/response formats, and authentication requirements.

## Base URL

All API requests are made to the following base URL:

<CodeGroup>
  ```bash theme={null}
  https://api.xentfi.com/v1
  ```
</CodeGroup>

## API Overview

The XentFi API is organized around REST principles. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

### Available Endpoints

| Category          | Base Path           | Description                            |
| ----------------- | ------------------- | -------------------------------------- |
| Master Wallets    | `/master-wallets`   | Create and manage hierarchical wallets |
| Deposit Addresses | `/addresses`        | Generate and manage deposit addresses  |
| Payment Links     | `/payment/links`    | Create hosted payment pages            |
| Payment Intents   | `/payment/intents`  | Manage payment sessions                |
| Settlement Rules  | `/settlement-rules` | Configure auto-settlement rules        |
| Transfers         | `/transfers`        | Execute cross-chain transfers          |
| Swaps             | `/swaps`            | Execute token swaps                    |
| Webhooks          | `/webhooks`         | Configure webhook endpoints            |
| AML               | `/aml`              | Sanctions screening and compliance     |

## Request Format

### Headers

All API requests must include the following headers:

| Header            | Required     | Description                     |
| ----------------- | ------------ | ------------------------------- |
| `apiKey`          | Yes          | Your API key from the dashboard |
| `appId`           | Yes          | Your application ID             |
| `Content-Type`    | For POST/PUT | `application/json`              |
| `Idempotency-Key` | Recommended  | Unique key for safe retries     |

### Example Request

<CodeGroup>
  ```bash theme={null}
  curl -X GET https://api.xentfi.com/v1/master-wallets \
    -H "apiKey: your-api-key" \
    -H "orgId: your-org-id"
  ```

  ```javascript theme={null}
  fetch('https://api.xentfi.com/v1/master-wallets', {
    headers: {
      'apiKey': 'your-api-key',
      'appId': 'your-app-id'
    }
  });
  ```

  ```python theme={null}
  import requests

  headers = {
      'apiKey': 'your-api-key',
      'appId': 'your-app-id'
  }

  response = requests.get('https://api.xentfi.com/v1/master-wallets', headers=headers)
  ```
</CodeGroup>

### List Response

For endpoints that return multiple resources:

```json theme={null}
{
    "data": {
        "items": [],
        "total": 0,
        "hasMore": false,
        "offset": 0,
        "limit": 50
    }
}
```

### Error Response

When an error occurs:

```json theme={null}
{
    "error": {
        "code": "ERROR_CODE",
        "message": "Human readable error message",
        "details": {},
        "timestamp": "2024-01-15T10:30:00.000Z",
        "requestId": "req_123e4567-e89b-12d3-a456-426614174000"
    }
}
```

## HTTP Status Codes

| Code | Meaning               | Description                                |
| ---- | --------------------- | ------------------------------------------ |
| 200  | OK                    | Request succeeded                          |
| 201  | Created               | Resource created successfully              |
| 400  | Bad Request           | Invalid request format or parameters       |
| 401  | Unauthorized          | Missing or invalid API key                 |
| 403  | Forbidden             | Valid API key but insufficient permissions |
| 404  | Not Found             | Requested resource doesn't exist           |
| 409  | Conflict              | Resource already exists                    |
| 422  | Unprocessable Entity  | Validation failed                          |
| 429  | Too Many Requests     | Rate limit exceeded                        |
| 500  | Internal Server Error | Server error, retry later                  |

## Pagination

For endpoints that return lists, pagination is supported using `offset` and `limit` parameters.

### Parameters

| Parameter | Type    | Default | Description                       |
| --------- | ------- | ------- | --------------------------------- |
| `offset`  | integer | 0       | Number of items to skip           |
| `limit`   | integer | 50      | Maximum items to return (max 100) |
| `order`   | string  | DESC    | Sort order (ASC or DESC)          |

### Example

```bash theme={null}
curl -X GET "https://api.xentfi.com/v1/master-wallets?offset=0&limit=20&order=DESC" \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id"
```

## Filtering

Many endpoints support filtering on various fields:

| Filter        | Format               | Example                          |
| ------------- | -------------------- | -------------------------------- |
| Date range    | `from` and `to`      | `?from=2024-01-01&to=2024-01-31` |
| Exact match   | `field=value`        | `?status=active`                 |
| Partial match | `field=value` (LIKE) | `?name=John`                     |

## Idempotency

For state-changing operations (POST, PUT, DELETE), you can include an `Idempotency-Key` header to safely retry requests without duplicating actions.

### How It Works

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API

    Client->>API: POST /v1/payment/links
    Note over Client,API: Idempotency-Key: key_123

    alt First Request
        API->>API: Process request
        API-->>Client: 201 Created
    else Duplicate Request
        API->>API: Detect duplicate key
        API-->>Client: 200 OK (cached response)
    end
```

### Best Practices

* Generate UUID v4 for each idempotency key
* Store keys for 24 hours
* Use same key for retries
* Different operations need different keys

## Rate Limiting

Rate limits are applied per API key and returned in response headers:

| Header                  | Description                         |
| ----------------------- | ----------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per window         |
| `X-RateLimit-Remaining` | Remaining requests in window        |
| `X-RateLimit-Reset`     | Time when window resets (UTC epoch) |

## Versioning

The API version is included in the URL path. We guarantee backward compatibility within the same major version.

```
https://api.xentfi.com/v1/...
```

### Version Lifecycle

| Version | Status  | Support Until |
| ------- | ------- | ------------- |
| v1      | Current | TBD           |
| v2      | Planned | Future        |

## SDKs

Official SDKs are available for popular languages:

| Language              | Package                       | Status      |
| --------------------- | ----------------------------- | ----------- |
| JavaScript/TypeScript | `@xentfi/sdk`                 | Coming soon |
| Python                | `xentfi`                      | Coming soon |
| Go                    | `github.com/xentfi/xentfi-go` | Coming soon |

## Support

* 📧 **API Support**: [api-support@xentfi.com](mailto:api-support@xentfi.com)
* 💬 **Discord**: [#api channel](https://discord.gg/xentfi)
* 📚 **Documentation**: [https://docs.xentfi.com](https://docs.xentfi.com)

## Next Steps

* [Authentication Guide](/api-reference/authentication) - Learn how to authenticate
* [Error Handling](/api-reference/errors) - Understand error responses
* [Master Wallets API](/api-reference/endpoint/list-master-wallets) - Make your first call