hydric Gateway SDK | Orientation Guide

@hydric/gateway

📚 Where to Find Things

@hydric/gateway

Installation

npm install @hydric/gateway

🎯 Mental Model: Resources

import { HydricGateway } from "@hydric/gateway";

const hydric = new HydricGateway({
  apiKey: process.env.HYDRIC_API_KEY,
});

// The resources:
hydric.multichainTokens; // Multi-chain token aggregation
hydric.singleChainTokens; // Single-chain token operations (faster)
hydric.tokenBaskets; // Curated token baskets of many sectors

Token Resource Selection Rule

• User mentions a specific chain? → Use

  singleChainTokens

• User wants global view? → Use

  multichainTokens

• User wants curated groups (stablecoins, BTCs, LSTs)? → Use

  tokenBaskets

⚡ Quick Start Pattern

// 1. Initialize
const hydric = new HydricGateway({ apiKey: "sk_..." });

// 2. Call a resource method
const { tokens } = await hydric.multichainTokens.search({
  search: "USDC",
  config: { limit: 10 },
});

// 3. Handle errors
try {
  const data = await hydric.tokenBaskets.getSingleChainById({
    chainId: 8453,
    basketId: "usd-stablecoins",
  });
} catch (error) {
  if (error instanceof HydricRateLimitError) {
    /* backoff */
  }
  if (error instanceof HydricNotFoundError) {
    /* handle not found */
  }
}

📦 Resource Cheat Sheet

multichainTokens

list()

search({ search })

singleChainTokens

list(chainId, params)

search(chainId, { search })

tokenBaskets

• list()

  - All baskets

• getMultiChainById({ basketId })

  - Basket across chains

• getSingleChainById({ chainId, basketId })

  - Basket on one chain

🚨 Critical Gotchas

1. Method Signatures Vary

// Multi-chain: params object only
hydric.multichainTokens.list({ config, filters });

// Single-chain: chainId FIRST, then params
hydric.singleChainTokens.list(8453, { config, filters });

2. Addresses Are Always Lowercase

3. Pagination Pattern

let cursor = null;
do {
  const { tokens, nextCursor } = await hydric.multichainTokens.list({
    config: { cursor, limit: 100 },
  });
  cursor = nextCursor; // null when done
} while (cursor);

4. Error Classes

instanceof

• HydricInvalidParamsError

  - Client-side validation failed

• HydricUnauthorizedError

  - API key issue

• HydricNotFoundError

  - Specific requested resource doesn't exist

• HydricRateLimitError

  - Too many requests for the API Key tier

• HydricError

  - Generic error

🧭 Common Workflows

Workflow 1: Global Token Search

// User: "Find USDC everywhere"
const { tokens } = await hydric.multichainTokens.search({ search: "USDC" });
// Each token has: addresses: [{ chainId: 1, address: '0x...' }, ...]

Workflow 2: Chain-Specific List

// User: "Show me top tokens on Base ordered by tvl"
const { tokens } = await hydric.singleChainTokens.list(8453, {
  config: { orderBy: { field: "tvl", direction: "desc" } },
});

Workflow 3: Basket Discovery

// User: "Get all stablecoins on Ethereum"
const { basket } = await hydric.tokenBaskets.getSingleChainById({
  chainId: 1,
  basketId: "usd-stablecoins",
});
// basket.tokens = [{ symbol: 'USDC', address: '0x...' }, ...]

🛠️ Implementation Checklist

• Is this single-chain or multi-chain? (Choose resource accordingly)
• Do I have the API key in environment variables?
• Am I using the correct method signature for the resource?
• Do I have error handling?
• If listing many results, did I implement pagination?

🔍 Quick Method Lookup

hydric.multichainTokens.list({ config, filters })

hydric.singleChainTokens.list(chainId, { config, filters })

hydric.multichainTokens.search({ search, config })

hydric.singleChainTokens.search(chainId, { search, config })

hydric.tokenBaskets.list()

hydric.tokenBaskets.getMultiChainById({ basketId })

hydric.tokenBaskets.getSingleChainById({ chainId, basketId })

📖 When You Need More

• Full parameter docs: https://docs.hydric.org/sdk-reference/typescript
• Docs MCP Server: Use the MCP server at https://docs.hydric.org/mcp for using the docs easily
• Source code: https://github.com/hydric-org/gateway-sdk/tree/main/sdks/typescript
• TypeScript types: Import from

  '@hydric/gateway'

  (e.g.,

  MultiChainTokenMetadata

  )

🎯 Golden Rules

1. Single-chain = singleChainTokens. Always prefer it when the chain is known.
2. ChainId first for single-chain methods, params object first for multi-chain.
3. Always lowercase when comparing addresses.
4. Paginate if you're fetching more than 100 results.
5. Catch errors with

   instanceof

   checks for precise handling if needed.

• ✅ Choose the right resource
• ✅ Remember method signatures
• ✅ Recall critical gotchas
• ✅ Know where to find complete docs