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.

• 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).

metadata

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.

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.

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.

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' } }

   .

1. POST /v1/tokens

   with

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

   .
2. Optionally filter by

   filters: { chainIds: [1, 8453] }

   .

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.

usd-stablecoins

eth-pegged-tokens

btc-pegged-tokens

eur-stablecoins

xau-stablecoins

monad-pegged-tokens

hype-pegged-tokens

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

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

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

• poolAddress

  can be 42-char address OR V4 bytes32 poolId.

protocols

poolTypes

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

• 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.

• 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.

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

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

• If

  protocols

  is provided,

  blockedProtocols

  is ignored.
• If

  poolTypes

  is provided,

  blockedPoolTypes

  is ignored.
• Empty arrays default to the blocklist approach.

./examples/

• 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

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.

• 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.

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.

• 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.