> For the complete documentation index, see [llms.txt](https://docs.cryptoix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cryptoix.io/developers/endpoints.md).

# Endpoints

This document provides a comprehensive reference for the Cryptoix Merchant API, enabling developers to integrate cryptocurrency payment processing, transaction management, and other financial operations into their applications.

**Base URL:** `https://api.cryptoix.io/v1`

***

## Authentication

All API requests must be authenticated using an API key. Include your API key in the `Authorization` header as a Bearer token.

```http
Authorization: Bearer YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key obtained from your Cryptoix merchant dashboard.

***

## Rate Limiting

The Cryptoix API is rate-limited to ensure stability and fair usage. The current limits are:

* **100 requests per minute** per API key.

If you exceed the rate limit, you will receive a `429 Too Many Requests` HTTP response. The response headers will include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` to help you manage your usage.

***

## Idempotency

To prevent accidental duplicate requests, you can use the `Idempotency-Key` header. This key should be a unique string (e.g., a UUID) generated by your client. If you send a request with the same `Idempotency-Key` within 24 hours, the API will return the result of the original request without re-processing it.

```http
Idempotency-Key: YOUR_UNIQUE_IDEMPOTENCY_KEY
```

***

## Versioning

The API is versioned using a URL path segment (e.g., `/v1`). We will strive to maintain backward compatibility within a major version. Breaking changes will be introduced in new major versions.

***

## Error Handling

Errors are returned in a standard JSON format:

```json
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The provided parameter 'amount' is invalid.",
    "details": "Amount must be a positive number."
  }
}
```

Common error codes include:

* `UNAUTHENTICATED`: API key is missing or invalid.
* `INVALID_PARAMETER`: A request parameter is missing, malformed, or invalid.
* `RESOURCE_NOT_FOUND`: The requested resource does not exist.
* `RATE_LIMITED`: You have exceeded the API rate limit.
* `INTERNAL_SERVER_ERROR`: An unexpected error occurred on the server.

***

## Payment Endpoints

These endpoints allow you to create and manage payment requests.

### 1. Create Payment Request

Creates a new payment request that a customer can use to pay.

* **HTTP Method:** `POST`
* **Path:** `/payments`
* **Authentication:** Required
* **Request Body:**

| Parameter        | Type   | Required | Description                                                                             |
| ---------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `amount`         | number | Yes      | The amount to be paid.                                                                  |
| `currency`       | string | Yes      | The currency of the amount (e.g., "USD", "EUR").                                        |
| `description`    | string | No       | A description for the payment.                                                          |
| `callback_url`   | string | No       | URL to redirect the customer to after payment completion or failure.                    |
| `metadata`       | object | No       | Key-value pairs for additional information.                                             |
| `customer_email` | string | No       | The email address of the customer.                                                      |
| `expires_at`     | string | No       | ISO 8601 timestamp for when the payment request expires (e.g., "2023-10-27T10:00:00Z"). |

**Example Request Body:**

```json
{
  "amount": 100.50,
  "currency": "USD",
  "description": "Order #12345",
  "callback_url": "https://your-merchant-site.com/payment/complete",
  "metadata": {
    "order_id": "12345"
  },
  "customer_email": "customer@example.com",
  "expires_at": "2023-10-27T10:00:00Z"
}
```

**Example Response:**

```json
{
  "id": "pay_req_abc123xyz789",
  "amount": 100.50,
  "currency": "USD",
  "status": "pending",
  "payment_url": "https://pay.cryptoix.io/pay/pay_req_abc123xyz789",
  "created_at": "2023-10-26T15:00:00Z",
  "expires_at": "2023-10-27T10:00:00Z",
  "description": "Order #12345",
  "callback_url": "https://your-merchant-site.com/payment/complete",
  "metadata": {
    "order_id": "12345"
  },
  "customer_email": "customer@example.com"
}
```

**Status Codes:**

* `201 Created`: Payment request created successfully.
* `400 Bad Request`: Invalid request parameters.
* `401 Unauthorized`: Invalid API key.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `INVALID_PARAMETER`: One or more parameters are invalid.
* `UNAUTHENTICATED`: API key is invalid.

**Example Usage (cURL):**

```bash
curl -X POST https://api.cryptoix.io/v1/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50,
    "currency": "USD",
    "description": "Order #12345",
    "callback_url": "https://your-merchant-site.com/payment/complete",
    "metadata": {
      "order_id": "12345"
    },
    "customer_email": "customer@example.com",
    "expires_at": "2023-10-27T10:00:00Z"
  }'
```

***

### 2. Retrieve Payment Request

Retrieves the details of a specific payment request.

* **HTTP Method:** `GET`
* **Path:** `/payments/{payment_request_id}`
* **Authentication:** Required
* **Path Parameters:**
  * `payment_request_id` (string, required): The unique identifier of the payment request.

**Example Response:**

```json
{
  "id": "pay_req_abc123xyz789",
  "amount": 100.50,
  "currency": "USD",
  "status": "paid",
  "payment_url": "https://pay.cryptoix.io/pay/pay_req_abc123xyz789",
  "created_at": "2023-10-26T15:00:00Z",
  "expires_at": "2023-10-27T10:00:00Z",
  "description": "Order #12345",
  "callback_url": "https://your-merchant-site.com/payment/complete",
  "metadata": {
    "order_id": "12345"
  },
  "customer_email": "customer@example.com",
  "paid_at": "2023-10-26T15:05:00Z",
  "paid_amount": 100.50,
  "paid_currency": "BTC",
  "transaction_id": "txn_def456uvw012"
}
```

**Status Codes:**

* `200 OK`: Payment request retrieved successfully.
* `401 Unauthorized`: Invalid API key.
* `404 Not Found`: Payment request not found.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `UNAUTHENTICATED`: API key is invalid.
* `RESOURCE_NOT_FOUND`: Payment request ID not found.

**Example Usage (cURL):**

```bash
curl -X GET https://api.cryptoix.io/v1/payments/pay_req_abc123xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

### 3. List Payment Requests

Retrieves a list of payment requests, with options for filtering and pagination.

* **HTTP Method:** `GET`
* **Path:** `/payments`
* **Authentication:** Required
* **Query Parameters:**
  * `limit` (integer, optional): Maximum number of results to return (default: 10, max: 100).
  * `starting_after` (string, optional): ID of the record after which to start the list.
  * `ending_before` (string, optional): ID of the record before which to end the list.
  * `status` (string, optional): Filter by payment status (e.g., `pending`, `paid`, `expired`, `failed`).
  * `created_after` (string, optional): ISO 8601 timestamp to filter payments created after this time.
  * `created_before` (string, optional): ISO 8601 timestamp to filter payments created before this time.

**Example Response:**

```json
{
  "data": [
    {
      "id": "pay_req_abc123xyz789",
      "amount": 100.50,
      "currency": "USD",
      "status": "paid",
      "payment_url": "https://pay.cryptoix.io/pay/pay_req_abc123xyz789",
      "created_at": "2023-10-26T15:00:00Z",
      "expires_at": "2023-10-27T10:00:00Z"
    },
    {
      "id": "pay_req_def456uvw012",
      "amount": 50.00,
      "currency": "EUR",
      "status": "pending",
      "payment_url": "https://pay.cryptoix.io/pay/pay_req_def456uvw012",
      "created_at": "2023-10-25T10:00:00Z",
      "expires_at": "2023-10-26T10:00:00Z"
    }
  ],
  "has_more": true,
  "url": "/v1/payments?limit=2&starting_after=pay_req_def456uvw012"
}
```

**Status Codes:**

* `200 OK`: Payment requests retrieved successfully.
* `401 Unauthorized`: Invalid API key.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `UNAUTHENTICATED`: API key is invalid.
* `INVALID_PARAMETER`: Invalid query parameter.

**Example Usage (cURL):**

```bash
curl -X GET "https://api.cryptoix.io/v1/payments?limit=2&status=pending" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Transaction Endpoints

These endpoints provide access to transaction data.

### 1. Retrieve Transaction

Retrieves details for a specific transaction.

* **HTTP Method:** `GET`
* **Path:** `/transactions/{transaction_id}`
* **Authentication:** Required
* **Path Parameters:**
  * `transaction_id` (string, required): The unique identifier of the transaction.

**Example Response:**

```json
{
  "id": "txn_def456uvw012",
  "payment_request_id": "pay_req_abc123xyz789",
  "amount": 100.50,
  "currency": "USD",
  "crypto_amount": 0.0005,
  "crypto_currency": "BTC",
  "status": "confirmed",
  "type": "payment",
  "created_at": "2023-10-26T15:05:00Z",
  "updated_at": "2023-10-26T15:10:00Z",
  "fee": 0.00001,
  "fee_currency": "BTC",
  "metadata": {
    "order_id": "12345"
  }
}
```

**Status Codes:**

* `200 OK`: Transaction retrieved successfully.
* `401 Unauthorized`: Invalid API key.
* `404 Not Found`: Transaction not found.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `UNAUTHENTICATED`: API key is invalid.
* `RESOURCE_NOT_FOUND`: Transaction ID not found.

**Example Usage (cURL):**

```bash
curl -X GET https://api.cryptoix.io/v1/transactions/txn_def456uvw012 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

### 2. List Transactions

Retrieves a list of transactions, with options for filtering and pagination.

* **HTTP Method:** `GET`
* **Path:** `/transactions`
* **Authentication:** Required
* **Query Parameters:**
  * `limit` (integer, optional): Maximum number of results to return (default: 10, max: 100).
  * `starting_after` (string, optional): ID of the record after which to start the list.
  * `ending_before` (string, optional): ID of the record before which to end the list.
  * `status` (string, optional): Filter by transaction status (e.g., `pending`, `confirmed`, `failed`, `refunded`).
  * `type` (string, optional): Filter by transaction type (e.g., `payment`, `payout`, `refund`).
  * `created_after` (string, optional): ISO 8601 timestamp to filter transactions created after this time.
  * `created_before` (string, optional): ISO 8601 timestamp to filter transactions created before this time.

**Example Response:**

```json
{
  "data": [
    {
      "id": "txn_def456uvw012",
      "payment_request_id": "pay_req_abc123xyz789",
      "amount": 100.50,
      "currency": "USD",
      "crypto_amount": 0.0005,
      "crypto_currency": "BTC",
      "status": "confirmed",
      "type": "payment",
      "created_at": "2023-10-26T15:05:00Z",
      "updated_at": "2023-10-26T15:10:00Z"
    },
    {
      "id": "txn_ghi789jkl345",
      "payment_request_id": null,
      "amount": 50.00,
      "currency": "EUR",
      "crypto_amount": 0.00025,
      "crypto_currency": "BTC",
      "status": "pending",
      "type": "payout",
      "created_at": "2023-10-26T14:00:00Z",
      "updated_at": "2023-10-26T14:00:00Z"
    }
  ],
  "has_more": true,
  "url": "/v1/transactions?limit=2&starting_after=txn_ghi789jkl345"
}
```

**Status Codes:**

* `200 OK`: Transactions retrieved successfully.
* `401 Unauthorized`: Invalid API key.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `UNAUTHENTICATED`: API key is invalid.
* `INVALID_PARAMETER`: Invalid query parameter.

**Example Usage (cURL):**

```bash
curl -X GET "https://api.cryptoix.io/v1/transactions?type=payment&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Invoice Endpoints

These endpoints allow you to create and manage invoices.

### 1. Create Invoice

Generates a new invoice for a customer.

* **HTTP Method:** `POST`
* **Path:** `/invoices`
* **Authentication:** Required
* **Request Body:**

| Parameter        | Type   | Required | Description                                                                                  |
| ---------------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `amount`         | number | Yes      | The total amount of the invoice.                                                             |
| `currency`       | string | Yes      | The currency of the invoice (e.g., "USD", "EUR").                                            |
| `description`    | string | No       | A description for the invoice.                                                               |
| `customer_name`  | string | No       | The name of the customer.                                                                    |
| `customer_email` | string | No       | The email address of the customer.                                                           |
| `due_date`       | string | No       | ISO 8601 date for when the invoice is due (e.g., "2023-11-15").                              |
| `items`          | array  | No       | An array of line items for the invoice. Each item can have `name`, `quantity`, `unit_price`. |
| `metadata`       | object | No       | Key-value pairs for additional information.                                                  |

**Example Request Body:**

```json
{
  "amount": 250.00,
  "currency": "USD",
  "description": "Consulting Services - October",
  "customer_name": "Acme Corp",
  "customer_email": "billing@acme.com",
  "due_date": "2023-11-15",
  "items": [
    {
      "name": "Web Development Hours",
      "quantity": 10,
      "unit_price": 25.00
    }
  ],
  "metadata": {
    "project_id": "PROJ-OCT-23"
  }
}
```

**Example Response:**

```json
{
  "id": "inv_ghi789jkl345",
  "amount": 250.00,
  "currency": "USD",
  "status": "draft",
  "description": "Consulting Services - October",
  "customer_name": "Acme Corp",
  "customer_email": "billing@acme.com",
  "due_date": "2023-11-15",
  "invoice_url": "https://merchant.cryptoix.io/invoices/inv_ghi789jkl345",
  "created_at": "2023-10-26T16:00:00Z",
  "items": [
    {
      "name": "Web Development Hours",
      "quantity": 10,
      "unit_price": 25.00
    }
  ],
  "metadata": {
    "project_id": "PROJ-OCT-23"
  }
}
```

**Status Codes:**

* `201 Created`: Invoice created successfully.
* `400 Bad Request`: Invalid request parameters.
* `401 Unauthorized`: Invalid API key.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `INVALID_PARAMETER`: One or more parameters are invalid.
* `UNAUTHENTICATED`: API key is invalid.

**Example Usage (cURL):**

```bash
curl -X POST https://api.cryptoix.io/v1/invoices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250.00,
    "currency": "USD",
    "description": "Consulting Services - October",
    "customer_name": "Acme Corp",
    "customer_email": "billing@acme.com",
    "due_date": "2023-11-15",
    "items": [
      {
        "name": "Web Development Hours",
        "quantity": 10,
        "unit_price": 25.00
      }
    ],
    "metadata": {
      "project_id": "PROJ-OCT-23"
    }
  }'
```

***

### 2. Retrieve Invoice

Retrieves the details of a specific invoice.

* **HTTP Method:** `GET`
* **Path:** `/invoices/{invoice_id}`
* **Authentication:** Required
* **Path Parameters:**
  * `invoice_id` (string, required): The unique identifier of the invoice.

**Example Response:**

```json
{
  "id": "inv_ghi789jkl345",
  "amount": 250.00,
  "currency": "USD",
  "status": "paid",
  "description": "Consulting Services - October",
  "customer_name": "Acme Corp",
  "customer_email": "billing@acme.com",
  "due_date": "2023-11-15",
  "invoice_url": "https://merchant.cryptoix.io/invoices/inv_ghi789jkl345",
  "created_at": "2023-10-26T16:00:00Z",
  "paid_at": "2023-10-26T16:30:00Z",
  "items": [
    {
      "name": "Web Development Hours",
      "quantity": 10,
      "unit_price": 25.00
    }
  ],
  "metadata": {
    "project_id": "PROJ-OCT-23"
  },
  "payment_request_id": "pay_req_mno789pqr123",
  "transaction_id": "txn_stu012vwx345"
}
```

**Status Codes:**

* `200 OK`: Invoice retrieved successfully.
* `401 Unauthorized`: Invalid API key.
* `404 Not Found`: Invoice not found.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `UNAUTHENTICATED`: API key is invalid.
* `RESOURCE_NOT_FOUND`: Invoice ID not found.

**Example Usage (cURL):**

```bash
curl -X GET https://api.cryptoix.io/v1/invoices/inv_ghi789jkl345 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

### 3. List Invoices

Retrieves a list of invoices, with options for filtering and pagination.

* **HTTP Method:** `GET`
* **Path:** `/invoices`
* **Authentication:** Required
* **Query Parameters:**
  * `limit` (integer, optional): Maximum number of results to return (default: 10, max: 100).
  * `starting_after` (string, optional): ID of the record after which to start the list.
  * `ending_before` (string, optional): ID of the record before which to end the list.
  * `status` (string, optional): Filter by invoice status (e.g., `draft`, `open`, `paid`, `past_due`, `void`).
  * `created_after` (string, optional): ISO 8601 timestamp to filter invoices created after this time.
  * `created_before` (string, optional): ISO 8601 timestamp to filter invoices created before this time.

**Example Response:**

```json
{
  "data": [
    {
      "id": "inv_ghi789jkl345",
      "amount": 250.00,
      "currency": "USD",
      "status": "paid",
      "description": "Consulting Services - October",
      "customer_email": "billing@acme.com",
      "due_date": "2023-11-15",
      "created_at": "2023-10-26T16:00:00Z"
    },
    {
      "id": "inv_mno789pqr123",
      "amount": 75.00,
      "currency": "USD",
      "status": "open",
      "description": "Support Contract - November",
      "customer_email": "support@acme.com",
      "due_date": "2023-11-30",
      "created_at": "2023-10-20T09:00:00Z"
    }
  ],
  "has_more": true,
  "url": "/v1/invoices?limit=2&starting_after=inv_mno789pqr123"
}
```

**Status Codes:**

* `200 OK`: Invoices retrieved successfully.
* `401 Unauthorized`: Invalid API key.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `UNAUTHENTICATED`: API key is invalid.
* `INVALID_PARAMETER`: Invalid query parameter.

**Example Usage (cURL):**

```bash
curl -X GET "https://api.cryptoix.io/v1/invoices?status=open&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Payout Endpoints

These endpoints facilitate sending cryptocurrency payouts to external addresses.

### 1. Create Payout

Initiates a cryptocurrency payout to a specified address.

* **HTTP Method:** `POST`
* **Path:** `/payouts`
* **Authentication:** Required
* **Request Body:**

| Parameter     | Type   | Required | Description                                                                  |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `amount`      | number | Yes      | The amount of cryptocurrency to send.                                        |
| `currency`    | string | Yes      | The cryptocurrency currency code (e.g., "BTC", "ETH", "USDT").               |
| `address`     | string | Yes      | The destination cryptocurrency address.                                      |
| `description` | string | No       | A description for the payout.                                                |
| `metadata`    | object | No       | Key-value pairs for additional information.                                  |
| `fee_level`   | string | No       | Optional: Network fee level ('low', 'medium', 'high'). Defaults to 'medium'. |

**Example Request Body:**

```json
{
  "amount": 0.001,
  "currency": "BTC",
  "address": "1A1zP1eP59kuX7a1234567890abcdefghij",
  "description": "Merchant payout for order #XYZ",
  "metadata": {
    "order_id": "XYZ"
  },
  "fee_level": "high"
}
```

**Example Response:**

```json
{
  "id": "payout_jkl345mno678",
  "amount": 0.001,
  "currency": "BTC",
  "status": "pending",
  "address": "1A1zP1eP59kuX7a1234567890abcdefghij",
  "description": "Merchant payout for order #XYZ",
  "created_at": "2023-10-26T17:00:00Z",
  "fee_level": "high",
  "metadata": {
    "order_id": "XYZ"
  }
}
```

**Status Codes:**

* `201 Created`: Payout initiated successfully.
* `400 Bad Request`: Invalid request parameters.
* `401 Unauthorized`: Invalid API key.
* `422 Unprocessable Entity`: Insufficient balance or invalid address.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `INVALID_PARAMETER`: One or more parameters are invalid.
* `UNAUTHENTICATED`: API key is invalid.
* `INSUFFICIENT_BALANCE`: Not enough funds to complete the payout.
* `INVALID_ADDRESS`: The provided cryptocurrency address is invalid.

**Example Usage (cURL):**

```bash
curl -X POST https://api.cryptoix.io/v1/payouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 0.001,
    "currency": "BTC",
    "address": "1A1zP1eP59kuX7a1234567890abcdefghij",
    "description": "Merchant payout for order #XYZ",
    "metadata": {
      "order_id": "XYZ"
    },
    "fee_level": "high"
  }'
```

***

### 2. Retrieve Payout

Retrieves the details of a specific payout.

* **HTTP Method:** `GET`
* **Path:** `/payouts/{payout_id}`
* **Authentication:** Required
* **Path Parameters:**
  * `payout_id` (string, required): The unique identifier of the payout.

**Example Response:**

```json
{
  "id": "payout_jkl345mno678",
  "amount": 0.001,
  "currency": "BTC",
  "status": "completed",
  "address": "1A1zP1eP59kuX7a1234567890abcdefghij",
  "description": "Merchant payout for order #XYZ",
  "created_at": "2023-10-26T17:00:00Z",
  "updated_at": "2023-10-26T17:05:00Z",
  "fee_paid": 0.00005,
  "fee_currency": "BTC",
  "transaction_id": "txn_uvw345xyz678",
  "metadata": {
    "order_id": "XYZ"
  }
}
```

**Status Codes:**

* `200 OK`: Payout retrieved successfully.
* `401 Unauthorized`: Invalid API key.
* `404 Not Found`: Payout not found.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `UNAUTHENTICATED`: API key is invalid.
* `RESOURCE_NOT_FOUND`: Payout ID not found.

**Example Usage (cURL):**

```bash
curl -X GET https://api.cryptoix.io/v1/payouts/payout_jkl345mno678 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

### 3. List Payouts

Retrieves a list of payouts, with options for filtering and pagination.

* **HTTP Method:** `GET`
* **Path:** `/payouts`
* **Authentication:** Required
* **Query Parameters:**
  * `limit` (integer, optional): Maximum number of results to return (default: 10, max: 100).
  * `starting_after` (string, optional): ID of the record after which to start the list.
  * `ending_before` (string, optional): ID of the record before which to end the list.
  * `status` (string, optional): Filter by payout status (e.g., `pending`, `processing`, `completed`, `failed`).
  * `created_after` (string, optional): ISO 8601 timestamp to filter payouts created after this time.
  * `created_before` (string, optional): ISO 8601 timestamp to filter payouts created before this time.

**Example Response:**

```json
{
  "data": [
    {
      "id": "payout_jkl345mno678",
      "amount": 0.001,
      "currency": "BTC",
      "status": "completed",
      "address": "1A1zP1eP59kuX7a1234567890abcdefghij",
      "created_at": "2023-10-26T17:00:00Z"
    },
    {
      "id": "payout_pqr678stu901",
      "amount": 0.05,
      "currency": "ETH",
      "status": "pending",
      "address": "0xAbCdEf1234567890aBcDeF1234567890aBcDeF12",
      "created_at": "2023-10-26T16:55:00Z"
    }
  ],
  "has_more": true,
  "url": "/v1/payouts?limit=2&starting_after=payout_pqr678stu901"
}
```

**Status Codes:**

* `200 OK`: Payouts retrieved successfully.
* `401 Unauthorized`: Invalid API key.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `UNAUTHENTICATED`: API key is invalid.
* `INVALID_PARAMETER`: Invalid query parameter.

**Example Usage (cURL):**

```bash
curl -X GET "https://api.cryptoix.io/v1/payouts?status=pending&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Webhook Endpoints

These endpoints allow you to receive real-time notifications about events occurring in your Cryptoix account.

### 1. Register Webhook Endpoint

Registers a URL to receive webhook events.

* **HTTP Method:** `POST`
* **Path:** `/webhooks`
* **Authentication:** Required
* **Request Body:**

| Parameter     | Type   | Required | Description                                                                              |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| `url`         | string | Yes      | The URL to send webhook events to.                                                       |
| `secret`      | string | No       | A secret key used to sign webhook events for verification.                               |
| `event_types` | array  | Yes      | An array of event types to subscribe to (e.g., `payment.succeeded`, `payout.completed`). |

**Example Request Body:**

```json
{
  "url": "https://your-merchant-site.com/webhooks/cryptoix",
  "secret": "YOUR_WEBHOOK_SECRET",
  "event_types": [
    "payment.succeeded",
    "payment.failed",
    "payout.completed",
    "invoice.paid"
  ]
}
```

**Example Response:**

```json
{
  "id": "whk_abc123def456",
  "url": "https://your-merchant-site.com/webhooks/cryptoix",
  "secret_provided": true,
  "event_types": [
    "payment.succeeded",
    "payment.failed",
    "payout.completed",
    "invoice.paid"
  ],
  "created_at": "2023-10-26T18:00:00Z"
}
```

**Status Codes:**

* `201 Created`: Webhook endpoint registered successfully.
* `400 Bad Request`: Invalid request parameters.
* `401 Unauthorized`: Invalid API key.
* `409 Conflict`: A webhook with this URL already exists.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `INVALID_PARAMETER`: One or more parameters are invalid.
* `UNAUTHENTICATED`: API key is invalid.
* `DUPLICATE_WEBHOOK`: Webhook URL already registered.

**Example Usage (cURL):**

```bash
curl -X POST https://api.cryptoix.io/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-merchant-site.com/webhooks/cryptoix",
    "secret": "YOUR_WEBHOOK_SECRET",
    "event_types": [
      "payment.succeeded",
      "payout.completed"
    ]
  }'
```

***

### 2. Retrieve Webhook Endpoint

Retrieves the details of a specific webhook endpoint.

* **HTTP Method:** `GET`
* **Path:** `/webhooks/{webhook_id}`
* **Authentication:** Required
* **Path Parameters:**
  * `webhook_id` (string, required): The unique identifier of the webhook endpoint.

**Example Response:**

```json
{
  "id": "whk_abc123def456",
  "url": "https://your-merchant-site.com/webhooks/cryptoix",
  "secret_provided": true,
  "event_types": [
    "payment.succeeded",
    "payment.failed",
    "payout.completed",
    "invoice.paid"
  ],
  "created_at": "2023-10-26T18:00:00Z"
}
```

**Status Codes:**

* `200 OK`: Webhook endpoint retrieved successfully.
* `401 Unauthorized`: Invalid API key.
* `404 Not Found`: Webhook endpoint not found.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `UNAUTHENTICATED`: API key is invalid.
* `RESOURCE_NOT_FOUND`: Webhook ID not found.

**Example Usage (cURL):**

```bash
curl -X GET https://api.cryptoix.io/v1/webhooks/whk_abc123def456 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

### 3. List Webhook Endpoints

Retrieves a list of all registered webhook endpoints.

* **HTTP Method:** `GET`
* **Path:** `/webhooks`
* **Authentication:** Required

**Example Response:**

```json
{
  "data": [
    {
      "id": "whk_abc123def456",
      "url": "https://your-merchant-site.com/webhooks/cryptoix",
      "event_types": [
        "payment.succeeded",
        "payment.failed"
      ],
      "created_at": "2023-10-26T18:00:00Z"
    },
    {
      "id": "whk_def456ghi789",
      "url": "https://another-site.com/hooks/cryptoix",
      "event_types": [
        "payout.completed"
      ],
      "created_at": "2023-10-25T11:00:00Z"
    }
  ],
  "has_more": false,
  "url": "/v1/webhooks"
}
```

**Status Codes:**

* `200 OK`: Webhook endpoints retrieved successfully.
* `401 Unauthorized`: Invalid API key.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `UNAUTHENTICATED`: API key is invalid.

**Example Usage (cURL):**

```bash
curl -X GET https://api.cryptoix.io/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

### 4. Delete Webhook Endpoint

Deletes a registered webhook endpoint.

* **HTTP Method:** `DELETE`
* **Path:** `/webhooks/{webhook_id}`
* **Authentication:** Required
* **Path Parameters:**
  * `webhook_id` (string, required): The unique identifier of the webhook endpoint to delete.

**Example Response:**

```json
{
  "id": "whk_abc123def456",
  "deleted": true
}
```

**Status Codes:**

* `200 OK`: Webhook endpoint deleted successfully.
* `401 Unauthorized`: Invalid API key.
* `404 Not Found`: Webhook endpoint not found.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `UNAUTHENTICATED`: API key is invalid.
* `RESOURCE_NOT_FOUND`: Webhook ID not found.

**Example Usage (cURL):**

```bash
curl -X DELETE https://api.cryptoix.io/v1/webhooks/whk_abc123def456 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Balance and Account Endpoints

These endpoints provide information about your merchant account balance and details.

### 1. Retrieve Account Balance

Retrieves the current balance of your merchant account across different currencies.

* **HTTP Method:** `GET`
* **Path:** `/balance`
* **Authentication:** Required

**Example Response:**

```json
{
  "available": {
    "USD": 1500.75,
    "BTC": 0.50000000,
    "ETH": 10.25000000
  },
  "pending": {
    "USD": 50.00,
    "BTC": 0.00000000,
    "ETH": 0.00000000
  },
  "currency_details": {
    "USD": {
      "minimum_withdrawal": 10.00
    },
    "BTC": {
      "minimum_withdrawal": 0.0001,
      "network_fee_estimate": {
        "low": 0.00001,
        "medium": 0.00002,
        "high": 0.00003
      }
    },
    "ETH": {
      "minimum_withdrawal": 0.001,
      "network_fee_estimate": {
        "low": 0.00005,
        "medium": 0.0001,
        "high": 0.00015
      }
    }
  }
}
```

**Status Codes:**

* `200 OK`: Balance retrieved successfully.
* `401 Unauthorized`: Invalid API key.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `UNAUTHENTICATED`: API key is invalid.

**Example Usage (cURL):**

```bash
curl -X GET https://api.cryptoix.io/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

### 2. Retrieve Account Details

Retrieves general information about your merchant account.

* **HTTP Method:** `GET`
* **Path:** `/account`
* **Authentication:** Required

**Example Response:**

```json
{
  "id": "acct_merchant123",
  "email": "merchant@example.com",
  "business_name": "Example Business Inc.",
  "created_at": "2022-01-15T09:00:00Z",
  "settings": {
    "display_currency": "USD",
    "language": "en",
    "timezone": "UTC"
  }
}
```

**Status Codes:**

* `200 OK`: Account details retrieved successfully.
* `401 Unauthorized`: Invalid API key.
* `429 Too Many Requests`: Rate limit exceeded.

**Error Codes:**

* `UNAUTHENTICATED`: API key is invalid.

**Example Usage (cURL):**

```bash
curl -X GET https://api.cryptoix.io/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Webhook Event Object Structure

When a webhook event is sent to your registered URL, it will be delivered as a POST request with a JSON body. The structure of the event object is as follows:

```json
{
  "event_id": "evt_a1b2c3d4e5f6",
  "event_type": "payment.succeeded",
  "created_at": "2023-10-26T15:05:00Z",
  "data": {
    // The payload object, specific to the event_type
    // Example for payment.succeeded:
    "id": "pay_req_abc123xyz789",
    "amount": 100.50,
    "currency": "USD",
    "status": "paid",
    "payment_url": "https://pay.cryptoix.io/pay/pay_req_abc123xyz789",
    "created_at": "2023-10-26T15:00:00Z",
    "paid_at": "2023-10-26T15:05:00Z",
    "paid_amount": 100.50,
    "paid_currency": "BTC",
    "transaction_id": "txn_def456uvw012"
  },
  "api_version": "v1"
}
```

**Verifying Webhook Signatures:**

To verify that a webhook event was genuinely sent by Cryptoix, you should use the `secret` you provided when registering the webhook. The signature is sent in the `Cryptoix-Signature` header of the request.

1. Concatenate the `event_id`, `event_type`, `created_at` timestamp, and the JSON `data` payload (as a string).
2. Compute the HMAC-SHA256 hash of this concatenated string using your `secret` as the key.
3. Compare the computed hash with the value in the `Cryptoix-Signature` header. They must match exactly.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cryptoix.io/developers/endpoints.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.