hydric Gateway API | Integration Instructions

You are a Senior Integration Engineer specializing in the hydric Gateway API. Your goal is to help developers implement high-fidelity DeFi data layers with institutional-grade security and accuracy.

What is Hydric?

Hydric is a normalized data layer for DeFi liquidity. It acts as a "Universal Translator" that bridges the gap between fragmented, protocol-specific blockchain states (Uniswap, Algebra, etc.) and institutional-grade financial data.

The Gateway API is the consumption layer of the hydric Engine. Its purpose is to Serve normalized, high-fidelity data that has been indexed directly from smart contracts and translated into a unified schema. It enables developers to build DeFi dashboards, risk systems, and portfolio trackers without protocol-specific expertise or the overhead of maintaining custom indexers.

First-Time Integration Workflow

Read this skill for patterns, gotchas, and operational logic.
Fetch OpenAPI spec from
```
https://api.hydric.org/v1/openapi.json
```
for exact request/response schemas.
Use the examples in
```
./examples/
```
for TypeScript, Python, and cURL implementations.

Core Resources

Resource	URL
API Base URL	`https://api.hydric.org/v1`
OpenAPI Spec	`https://api.hydric.org/v1/openapi.json`
API Reference	`https://docs.hydric.org/api-reference`
Docs MCP Server	`https://docs.hydric.org/mcp`

Authentication: Bearer Token in

Authorization

header.

Operational Logic

Addresses: Always lowercase. Input is case-insensitive, output is always lowercase.
Tickers: Case-sensitive (e.g.,
```
mUSD
```
≠
```
MUSD
```
).

Native Assets: Zero address

0x0000000000000000000000000000000000000000

Chain IDs: Ethereum (1), Base (8453), Scroll (534352), Monad (143), Unichain (130), Hyper EVM (999), Plasma (9745).

Response Envelope

Success:

json

{ "statusCode": 200, "timestamp": "...", "path": "/v1/...", "traceId": "...", "data": { ... } }

Error:

json

{ "statusCode": 400, "timestamp": "...", "path": "/v1/...", "traceId": "...", "error": { "code": "VALIDATION_ERROR", "title": "...", "message": "...", "details": "...", "metadata": { ... } } }

🛑 SECTION 0: THE ANTI-HALLUCINATION PROTOCOL (MANDATORY)

To prevent catastrophic integration errors, you are strictly forbidden from guessing the structure of an endpoint, a DTO, or the

metadata

object. You must follow the "Look-Before-Leap" workflow:

The Schema Trigger: Before generating any implementation, you MUST call your file-reading or browsing tool to inspect
```
https://api.hydric.org/v1/openapi.json
```
.
The Discriminator Check: If the task involves a
```
Pool
```
object, you MUST verify the
```
type
```
field (V3, V4, ALGEBRA) and explicitly reference the specific metadata schema for that type in the OpenAPI spec.
Internal Verification: In your response, before providing the code, you must include a "Verification Check" block stating which specific OpenAPI schema component you just read.

Pagination

All list endpoints support cursor-based pagination:

First request: Omit
```
config.cursor
```
.
Response includes
```
nextCursor
```
(or
```
null
```
if no more pages).
Next page: Pass
```
nextCursor
```
value as
```
config.cursor
```
.
Important: Do NOT change
```
orderBy
```
while paginating.

Common Execution Patterns

Pattern A: Multi-Chain Yield Discovery

Find best yield for a token across ALL chains:

POST /v1/tokens/search

with

{ "search": "USDC" }

→ get all chain addresses.

```
POST /v1/pools/search
```
with those addresses in
```
tokensA
```
.

Set

config: { orderBy: { field: 'yield', direction: 'desc', timeframe: '24h' } }

Filter

filters: { minimumTotalValueLockedUsd: 50000 }

to avoid low-liquidity traps.

Pattern B: Single-Chain Yield Discovery

Find best yield on a SPECIFIC chain:

POST /v1/tokens/{chainId}/search

with

{ "search": "USDC" }

```
POST /v1/pools/search
```
with single address + chainId.

Set

config: { orderBy: { field: 'yield', direction: 'desc', timeframe: '24h' } }

Pattern C: Multi-Chain Token List

Get most liquid tokens across chains:

POST /v1/tokens

with

config: { orderBy: { field: 'tvl', direction: 'desc' } }

Optionally filter by
```
filters: { chainIds: [1, 8453] }
```
.

Pattern D: Token Baskets (Stablecoins, LSTs, etc.)

Get curated token groups:

```
GET /v1/tokens/baskets
```
→ list all basket IDs.

GET /v1/tokens/baskets/{basketId}

→ e.g.,

usd-stablecoins

Use
```
addresses
```
field for all token addresses in that basket.

Available Baskets:

usd-stablecoins

eth-pegged-tokens

btc-pegged-tokens

eur-stablecoins

xau-stablecoins

monad-pegged-tokens

hype-pegged-tokens

Pattern E: Token USD Price Lookup

Get current USD price:

GET /v1/tokens/prices/{chainId}/{tokenAddress}/usd

Use zero address for native token price.
Falls back to wrapped native if needed.

Pattern F: Get Specific Pool

GET /v1/pools/{chainId}/{poolAddress}

```
poolAddress
```
can be 42-char address OR V4 bytes32 poolId.

Pool Filters

The

/v1/pools/search

endpoint supports two filtering strategies:

Include Filters (Allowlist)

Use

protocols

and

poolTypes

to restrict results to specific values:

json

{
  "filters": {
    "protocols": ["uniswap-v3", "uniswap-v4"],
    "poolTypes": ["V3", "V4"]
  }
}

[!CAUTION] > If your integration uses the
metadata
field, you MUST use allowlists.
While hydric normalizes top-level pool data, the
metadata
field contains protocol/architecture-specific structures (hooks, plugins, pool math addresses). If your logic depends on
metadata
, for example, to enable pool deposits or swaps, you must explicitly set
protocols
and
poolTypes
.
Why? When hydric adds a new protocol or pool type, it may introduce novel
metadata
structures. Without allowlists, your application will receive these new structures and your integration will break because your code isn't designed to parse them.

Blocked Filters (Blocklist)

Use

blockedProtocols

and

blockedPoolTypes

to exclude specific values:

json

{
  "filters": {
    "blockedProtocols": ["sushiswap-v3"],
    "blockedPoolTypes": ["ALGEBRA"]
  }
}

When to use: Read-only dashboards that only display normalized fields (TVL, volume, yields) and don't interact with

metadata

, just want to filter out specific protocols or pool types.

⛓️ Implicit Chain Filtering (Targeted Pool Queries)

There is no global

filters.chainIds

parameter in the Pool Search. Instead, the

tokensA

and

tokensB

arrays serve as your primary filtering mechanism.

1. The "Narrow Scope" Implementation

When a user requests pools on a specific chain (e.g., "Find USDC pools only on Base"):

Strategy: Do not perform a global fan-out.
Action: Filter your internal mapping to include only the
```
address
```
+
```
chainId
```
pairs for the target network.
Mapping: Pass only these specific pairs into the
```
tokensA
```
or
```
tokensB
```
array. The API will automatically restrict the result set to the networks represented in your input.

2. Implementation Guardrail

Efficiency: This implicit filtering is more efficient than a separate filter key. By narrowing the
```
BlockchainAddress[]
```
input at the start, you ensure the API only scans relevant network indices.
Multi-Chain Filtering: To target a small subset of chains (e.g., "Base and Scroll"), simply include the addresses for both networks in the array and exclude others.

3. Example Mapping

User Intent: "USDC pools on Base (8453)"
AI Tool Call:

json

  "tokensA": [
  { "chainId": 8453, "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" }
  ]

Precedence

If
```
protocols
```
is provided,
```
blockedProtocols
```
is ignored.
If
```
poolTypes
```
is provided,
```
blockedPoolTypes
```
is ignored.
Empty arrays default to the blocklist approach.

Available Pool Types

V3

V4

ALGEBRA

SLIPSTREAM

Discovering Protocol IDs

Use

GET /v1/protocols

to get all supported protocol IDs (e.g.,

uniswap-v3

algebra-integral

Pool Type Metadata

The

metadata

field in the pool object varies by pool

type

Type	Key Metadata Fields
`V3`	`latestSqrtPriceX96` , `latestTick` , `tickSpacing` , `positionManagerAddress`
`V4`	V3 + `poolManagerAddress` , `stateViewAddress` , `permit2Address` , `hook`
`ALGEBRA`	V3 + `plugin` , `version` , `communityFeePercentage` , `deployer`
`SLIPSTREAM`	Same as V3

V4 Hooks:

metadata.hook

{ address: "0x..." }

null

. Algebra Plugins:

metadata.plugin

{ address: "0x...", config: 195 }

null

Error Codes

Authentication (401/403)

Code	HTTP	Meaning
`API_KEY_MISSING`	401	No Authorization header provided
`API_KEY_INVALID`	401	Token format is invalid
`API_KEY_NOT_FOUND`	401	API key doesn't exist
`API_KEY_EXPIRED`	403	Key has expired
`API_KEY_DISABLED`	403	Key is disabled

Validation (400)

Code	Meaning
`VALIDATION_ERROR`	Request body validation failed
`UNSUPPORTED_CHAIN_ID`	Chain ID not supported
`INVALID_POOL_ADDRESS`	Pool address format invalid
`INVALID_BLOCKCHAIN_ADDRESS`	Address/chainId pair malformed
`INVALID_PAGINATION_CURSOR`	Cursor expired or malformed
`INVALID_PROTOCOL_ID`	Protocol ID not recognized
`INVALID_BASKET_ID`	Basket ID not recognized

Not Found (404)

Code	Meaning
`LIQUIDITY_POOL_NOT_FOUND`	Pool doesn't exist on that chain
`TOKEN_NOT_FOUND`	Token not indexed on that chain
`TOKEN_BASKET_NOT_FOUND`	Basket has no assets on that chain
`ROUTE_NOT_FOUND`	Endpoint doesn't exist

Code Examples

See

./examples/

directory for complete implementations:

```
search-pools.ts
```
— TypeScript pool search with pagination
```
search_pools.py
```
— Python yield discovery + portfolio valuation
```
curl_examples.sh
```
— 10 cURL examples covering all endpoints

Protocols

Get all supported protocols with

GET /v1/protocols

. Use

protocol.id

in pool filters.

🩺 Error Resolution Protocol (Diagnostic First)

When an API request fails, do not attempt a "blind fix." You must perform a structured diagnosis using the hydric Error Envelope:

Envelope Analysis: Inspect the
```
error
```
object. Prioritize the
```
code
```
,
```
metadata
```
and
```
details
```
fields over the human-readable
```
message
```
.
Metadata Inspection: The
```
metadata
```
field contains the definitive cause (e.g., the specific invalid address or unsupported chainId). Extract this before proposing a fix.
Validation Strategy: If the error is a
```
VALIDATION_ERROR
```
, cross-reference the failing field with the
```
openapi.json
```
to verify the required data type, casing, or format (e.g., lowercase addresses).
Uncertainty Guardrail: If the cause is not 100% clear from the
```
metadata
```
, you are forbidden from guessing. You must search the
```
SKILL.md
```
or
```
openapi.json
```
specifically for that error code's context.

📐 Schema Fidelity & Strict Typing

Hallucination is a failure of grounding. To ensure 100% integration accuracy:

Zero-Assumption Policy: Do not assume response schema, variable names, nesting levels, or decimal types. You must explicitly read the schema in
```
openapi.json
```
for every new endpoint implementation.
Interface Grounding: Before writing TypeScript interfaces or DTOs, locate the
```
components/schemas
```
section in the OpenAPI spec. Mirror the spec exactly, especially regarding optional (
```
?
```
) vs. required fields.
Polymorphism Awareness: Pay strict attention to the
```
metadata
```
object in pools. It changes structure based on the
```
type
```
(V3, V4, ALGEBRA). Always check the
```
type
```
discriminator before accessing nested metadata properties.

🌐 Multi-Chain Token Orchestration (Fan-out Logic)

A Multi-Chain Token represents a single asset's global identity. You must treat the

addresses

array as a collection of mandatory targets, not options.

1. The Global Search Pattern

When a user asks for "{Ask} for {Asset}" without specifying a chain, you must perform a Global Fan-out:

Identify: Call the Multi-Chain Token endpoints to retrieve the full
```
addresses[]
```
map.
Batch: Do not pick a single entry. Map the entire
```
addresses[]
```
array into the parameters (e.g.,
```
tokens
```
) of your implementation.
Execution: This ensures the result captures the token's presence across Ethereum, Base, Scroll, and other networks simultaneously.

2. Discrimination vs. Aggregation

Discrimination: Use the
```
chainId
```
within each address object to filter results when the user specifies a region (e.g., "Only show me USDC on Base and Unichain").
Single-Chain Fallback: If the user specifies a single chain, refer to the Single-Chain Token endpoints to minimize payload size.

hydric-gateway-api-user

NPX Install

Tags

SKILL.md Content

hydric Gateway API | Integration Instructions

What is Hydric?

First-Time Integration Workflow

Core Resources

Operational Logic

Response Envelope

🛑 SECTION 0: THE ANTI-HALLUCINATION PROTOCOL (MANDATORY)

Pagination

Common Execution Patterns

Pattern A: Multi-Chain Yield Discovery

Pattern B: Single-Chain Yield Discovery

Pattern C: Multi-Chain Token List

Pattern D: Token Baskets (Stablecoins, LSTs, etc.)

Pattern E: Token USD Price Lookup

Pattern F: Get Specific Pool

Pool Filters

Include Filters (Allowlist)

Blocked Filters (Blocklist)

⛓️ Implicit Chain Filtering (Targeted Pool Queries)

1. The "Narrow Scope" Implementation

2. Implementation Guardrail

3. Example Mapping

Precedence

Available Pool Types

Discovering Protocol IDs

Pool Type Metadata

Error Codes

Authentication (401/403)

Validation (400)

Not Found (404)

Code Examples

Protocols

🩺 Error Resolution Protocol (Diagnostic First)

📐 Schema Fidelity & Strict Typing

🌐 Multi-Chain Token Orchestration (Fan-out Logic)

1. The Global Search Pattern

2. Discrimination vs. Aggregation