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

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

Core Resources

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:

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

Error:

{ "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:

1. 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.
2. 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.
3. 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:

1. First request: Omit config.cursor.
2. Response includes nextCursor (or null if no more pages).
3. Next page: Pass nextCursor value as config.cursor.
4. 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:

1. POST /v1/tokens/search with { "search": "USDC" } → get all chain addresses.
2. POST /v1/pools/search with those addresses in tokensA.
3. Set config: { orderBy: { field: 'yield', direction: 'desc', timeframe: '24h' } }.
4. Filter filters: { minimumTotalValueLockedUsd: 50000 } to avoid low-liquidity traps.

Pattern B: Single-Chain Yield Discovery

Find best yield on a SPECIFIC chain:

1. POST /v1/tokens/{chainId}/search with { "search": "USDC" }.
2. POST /v1/pools/search with single address + chainId.
3. Set config: { orderBy: { field: 'yield', direction: 'desc', timeframe: '24h' } }.

Pattern C: Multi-Chain Token List

Get most liquid tokens across chains:

1. POST /v1/tokens with config: { orderBy: { field: 'tvl', direction: 'desc' } }.
2. Optionally filter by filters: { chainIds: [1, 8453] }.

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

Get curated token groups. There are two ways to use baskets:

1. The Manual Extraction Workflow (Read-Only):

1. GET /v1/tokens/baskets → list all basket IDs.
2. GET /v1/tokens/baskets/{basketId} → e.g., usd-stablecoins.
3. Use addresses field for all token addresses in that basket.

2. The Accelerated Search Workflow (Server-Side Resolution): When searching for pools, you do not need to extract the token addresses manually. You can pass the baskets directly to the API, and the Gateway will resolve them server-side into tokens. Be sure to provide at least one of basketsA or tokensA.

POST /v1/pools/search
{
  "basketsA": [
    {
      "basketId": "usd-stablecoins",
      "chainIds": [1, 8453] // Optional: filters the basket before searching. If not provided, the basket will be searched across all chains.
    }
  ],
  "tokensB": [
    { "chainId": 1, "address": "0x0000000000000000000000000000000000000000" }
  ]
}

Note: This request will find pools containing ANY stablecoin on Ethereum/Base matched against Native ETH on Ethereum.

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:

{
  "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:

{
  "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. Basket Chain Filtering

The same implicit filtering logic applies to IBlockchainBasket objects provided in basketsA or basketsB. If you pass a chainIds array (e.g., [8453]) inside the basket object, the searching engine will explicitly constrain the basket's tokens to only those that exist on the requested chains before searching. If chainIds is completely omitted from the basket object, it defaults to all available networks for that basket.

3. Implementation Guardrail

• Validation Rule (HasTokensOrBaskets): For both Side A and Side B, the API requires that you provide at least one search parameter. For example, tokensA OR basketsA MUST contain at least one element. You cannot send an empty array for both. If a side is providing the constraint, make sure to populate either the tokens or baskets array.
• 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:

  "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:

V4 Hooks: metadata.hook is { address: "0x..." } or null. Algebra Plugins: metadata.plugin is { address: "0x...", config: 195 } or null.

Error Codes

Authentication (401/403)

Validation (400)

Not Found (404)

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:

1. Envelope Analysis: Inspect the error object. Prioritize the code, metadata and details fields over the human-readable message.
2. Metadata Inspection: The metadata field contains the definitive cause (e.g., the specific invalid address or unsupported chainId). Extract this before proposing a fix.
3. 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).
4. 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:

1. Identify: Call the Multi-Chain Token endpoints to retrieve the full addresses[] map.
2. Batch: Do not pick a single entry. Map the entire addresses[] array into the parameters (e.g., tokens) of your implementation.
3. 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.