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

# API Reference

> Technical specifications and integration standards for the hydric Gateway API.

<Note>
  **Private Beta:** hydric is currently accessible to a select group of
  partners. To request access to our infrastructure, please reach out to our
  [Engineering Support](mailto:support@hydric.org) via email.
</Note>

The hydric Gateway API is a high-performance REST interface designed for deterministic access to normalized DeFi liquidity data. All endpoints are served over HTTPS and return standard JSON payloads.

## Gateway URL

The hydric Gateway API is globally distributed at:

| Environment    | Base URL                    |
| :------------- | :-------------------------- |
| **Production** | `https://api.hydric.org/v1` |

## Gateway API AI Skill

For developers using AI agents or LLM-based workflows, we provide a specialized **AI Skill** for the hydric Gateway API. This enables your AI assistant to understand the `HydricGateway` API easily and find the right code examples and resources in the documentation.

### Quick Installation

Add the skill to your project using [skills.sh](https://skills.sh/):

```bash theme={null}
npx skills add https://github.com/hydric-org/skills --skill hydric-gateway-api-user
```

After running this command, your AI assistant will have access to the hydric Gateway API skill.

## Authentication

hydric uses API keys to allow access to the API.

### Usage

To authenticate your requests, include your API key in the `Authorization` header as a Bearer token. This follows the standard pattern for secure API access.

### Request Header Structure

Authorization: `Bearer YOUR_API_KEY`

### Example Request (cURL)

```bash theme={null}
curl https://api.hydric.org/v1/protocols -H "Authorization: Bearer YOUR_API_KEY"
```

### Response Codes

If your authentication fails, the API will return one of the following status codes to help you troubleshoot:

#### 401 Unauthorized

**Description:**\
The API key is missing or malformed.

**Solution:**\
Verify that your header includes the `Bearer` prefix followed by a space and your key.

#### 403 Forbidden

**Description:**\
The API key is valid, but the account lacks permission.

**Solution:**\
Check if your key has been deactivated or if you are attempting to access a restricted resource.

### Best Practices & Security

To keep your account and data safe, follow these guidelines:

* **Keep Keys Private**\
  Never include your API key in client-side code (browsers, mobile apps) or public repositories like GitHub.

* **Use Environment Variables**\
  Store your keys in `.env` files or secure secret management systems instead of hardcoding them.

* **Rotate Regularly**\
  If you suspect your key has been compromised, rotate it immediately.

### Testing in the Documentation

You can test endpoints directly in these docs. Click the **Try It** button on any endpoint page, paste your key into the authentication field, and see live results instantly.

## Supported Blockchains

<Expandable title="Liquidity Pools: Supported Blockchains">
  [comment]: <> "This file is auto-generated. Do not modify manually. Changes will be overwritten."

  | Chain Name | Chain ID |
  | :--------- | :------- |
  | Base       | 8453     |
  | Ethereum   | 1        |
  | Hyper EVM  | 999      |
  | Monad      | 143      |
  | Plasma     | 9745     |
  | Scroll     | 534352   |
  | Unichain   | 130      |
</Expandable>

## Response Architecture

Every request to the hydric Gateway Layer follows a consistent response structure. Our goal is to provide actionable intelligence that can be parsed safely in production environments.

### Success Patterns

All successful responses return a `200 OK` status. Data is always encapsulated in a top-level object to allow for future metadata expansion without breaking your integration.

### Error Handling

When a request cannot be fulfilled, hydric returns a structured error object. We provide deep context to ensure that your automated systems can handle failures gracefully.

**Error Schema:**

* **`status`**: The standard HTTP status code.
* **`code`**: A machine-readable hydric-specific error string (e.g., `INSUFFICIENT_LIQUIDITY_DATA`).
* **`message`**: A concise, human-readable summary of the issue.
* **`details`**: Technical hints, suggestions, or stack-trace fragments to accelerate debugging.
* **`metadata`**: Context-specific data, such as the specific input value that triggered a validation failure.

For a complete mapping of error types and recovery strategies, see the [Error Codes](/api-reference/error-codes) documentation.

## Implementation Rules

To ensure system stability and fair access for all partners, the following rules apply to all Gateway interactions:

* **Content Type:** All requests must include the `Content-Type: application/json` header.
* **Rate Limiting:** Every API key is subject to a rate limit. Exceeding this limit will return a `429 Too Many Requests` error.
* **Versioning:** The API is versioned via the URL (e.g., `/v1`). Breaking changes will never be introduced to an existing version.