DEV Community: Tribulnation Labs

Introducing Typed: Exchange Clients That Actually Work

Tribulnation Labs — Wed, 01 Jul 2026 17:17:06 +0000

The problem with exchange APIs

Every exchange has an API. Most of them are bad.

Not broken — just bad in the quiet, invisible way that costs you hours. The response says "side": "buy" but the docs say it should be "BUY". The timestamp is milliseconds on one endpoint and seconds on another. A field is documented as optional but always present — until one day it isn't. Error codes live in a different section of the docs than the endpoint that throws them.

You don't discover any of this until you're live.

We trade our own capital on these venues. We built our own tools to do it. At some point we realised that the client layer — the thing that sits between your code and the exchange — was doing far more work than it should, and none of it was being shared.

What Typed is

Typed is a collection of async, typed, validated Python clients for crypto exchanges. One package per venue. One consistent interface. Zero surprises.

Each client:

Is fully typed — every request parameter, every response field, annotated with Python types you can actually use
Is validated at the boundary — responses are parsed and checked before they reach your code, so you catch bad data from the exchange, not bad assumptions in your logic
Is async-first — built on httpx and asyncio, no sync wrappers bolted on after the fact
Uses plain Python types wherever possible — no mandatory SDK imports to construct a simple parameter

A real example:

from typed_hyperliquid import HyperliquidClient

async with HyperliquidClient() as client:
    fills = await client.get_user_fills(address="0xabc...")
    for fill in fills:
        print(fill.coin, fill.side, fill.sz, fill.px)

fill.side is a Literal["A", "B"], not a raw string. fill.px is a Decimal, not "101000.0". You know what you're working with.

Why open source

We use every line of this on our own book. That means it has to be correct — not test-correct, but production-correct. When Hyperliquid changes their API, we notice within hours because our own trading breaks.

That's a higher standard of maintenance than most open-source projects get. Making it public costs us nothing, and it might save someone else the week we spent figuring out the edge cases.

The packages are published under GPLv3 on PyPI under the typed-* namespace.

What's available

Four clients are in production today:

typed-hyperliquid — full coverage of the Hyperliquid API, including WebSocket streams
typed-alchemy — Alchemy's NFT, token, and transaction APIs
typed-mexc — MEXC spot and futures APIs
typed-dydx — dYdX v4 indexer, chain modules, Comet RPC, and order placement

Several more are in active development: Ethereum, Etherscan, Bit2Me. Planned: Bybit, Binance, Bitget.

You can track progress on the Typed page.

Install

pip install typed-hyperliquid
pip install typed-alchemy
pip install typed-mexc
pip install typed-dydx

Feedback, issues, and PRs welcome on GitHub.

Introducing Tribulnation Catalogue: One ID for Every Asset, Everywhere

Tribulnation Labs — Sun, 28 Jun 2026 12:26:24 +0000

The naming problem

Every exchange invented its own names for everything.

Here's what six exchanges call the BNB Chain network:

Exchange	Their string
Binance	`BSC`
MEXC	`BNB Smart Chain(BEP20)`
Bitget	`BEP20`
KuCoin	`BSC`
Bybit	`BSC (BEP20)`
Kraken	`BNB Chain`

Same story with assets. Kraken calls Bitcoin XXBT. Hyperliquid calls it 197. Everyone else calls it BTC.

If you've built anything that touches more than one exchange, you've spent time on this. Tribulnation Catalogue is the translation layer — a free, open dataset of canonical crypto assets, networks, and instruments, with per-exchange translation tables baked in.

API

Every record is available as a static JSON API — no auth, no rate limits, served from GitHub Pages.

Browse: catalogue.tribulnation.com

GET /api/assets.json
GET /api/assets/{id}.json
GET /api/platforms.json
GET /api/platforms/{id}.json
GET /api/instruments/spot/{platform}.json
GET /api/instruments/perpetual/{platform}.json
GET /api/indexes/symbols.json
GET /api/indexes/external/coingecko.json

Full route list and interactive try-it at catalogue.tribulnation.com/api.

You can also download everything at once:

Archive	Contents
`data.zip`	Raw catalogue data (JSON)
`icons.zip`	SVG icons for assets, platforms, networks

Clients

Python

pip install tribulnation-catalogue

from tribulnation.catalogue import Catalogue

catalogue = Catalogue.load()

btc     = catalogue.assets['bitcoin']
binance = catalogue.platforms['binance']

Catalogue.load() downloads the catalogue on first use and caches it locally.

JavaScript / TypeScript

npm install @tribulnation/catalogue

import { Catalogue } from '@tribulnation/catalogue';

const client = new Catalogue();
const matches = await client.findBySymbol('BTC');
const bitcoin = await client.fetchAsset('bitcoin');
const pairs   = await client.getSpotInstruments('mexc');

Pricing

The MarketData SDK uses each asset's external IDs to route price requests to the right provider automatically:

from tribulnation.catalogue import Catalogue, MarketData

catalogue = Catalogue.load()
sdk = MarketData.new('usd', 'coingecko', 'twelvedata', 'alphavantage')

await sdk.current_price(catalogue.assets['bitcoin'])                  # → CoinGecko
await sdk.current_price(catalogue.assets['gold'])                     # → Twelve Data
await sdk.current_price(catalogue.assets['west-texas-intermediate'])  # → Alpha Vantage

Provider	Source	Covers
CoinGecko	`'coingecko'`	Crypto — price, market cap, history
CoinMarketCap	`'coinmarketcap'`	Crypto — price, market cap, history
Twelve Data	`'twelvedata'`	Precious metals (XAU, XAG†), forex
Alpha Vantage	`'alphavantage'`	Energy & agricultural commodities, forex

† XAG requires a paid Twelve Data plan.

What's inside

Assets — canonical records keyed by slug (e.g. bitcoin, usd-coin). Each carries a display name, symbol, icon, tags, peg information for stablecoins and wrapped tokens, and external IDs for CoinGecko, CoinMarketCap, Twelve Data, and Alpha Vantage.

Platforms — trading venues and blockchain networks keyed by slug (e.g. binance, ethereum). Blockchains carry namespace, chain ID, native asset, and EVM/SVM category.

Instruments — spot pairs, perpetual futures, debt positions, and liquidity pools — each mapped to canonical asset IDs. Resolves exchange-specific tickers like XBTUSDT back to ('bitcoin', 'tether').

Translations — per-exchange asset and network name mappings. The BNB Chain table above is real data from this.

Icons — square, maskable SVGs for assets, platforms, and networks. Designed to be displayed cropped to a circle or rounded square; API responses include absolute icon URLs.

Contributing

The data lives in plain JSON files — easy to read, easy to contribute to.

git clone https://github.com/tribulnation/catalogue.git
cd catalogue
python -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python scripts/validate.py

New assets, platforms, icons, translations, and corrections welcome on GitHub.

The Proper Way to Write API Clients

Tribulnation Labs — Sun, 28 Jun 2026 11:58:12 +0000

Introduction

Details matter. Developer experience matters. Every unnecessary import, every unnecessary check on the docs because the type hints are lacking, every hard-to-understand feature, every hard-coded quirk the user can’t turn off—these matter.

So, some guidelines are obvious:

Inputs shouldn’t require custom imports
Annotate types precisely
Avoid unnecessary complication
Provide extra behavior optionally

Let’s unpack them and give examples one by one.

1. Inputs shouldn’t require custom imports

So simple, yet so commonly ignored. How often do you see this?

from sdk.deeply.nested.path.to.the.method.module import Parameters

await client.get_user(Parameters(email='...'))

I don’t want to walk your stupid repo at every god-damn call! No, give me a TypedDict instead, for pity’s sake. This way I still get the type safety, and no import required:

# SDK code
class Parameters(TypedDict):
    email: str

async def get_user(self, parameters: Parameters):
    ...

# user code
await client.get_user({ 'email': '...' })

Isn’t that nicer?

2. Annotate types precisely

Nothing frustrates me more than an API “SDK” that looks like this:

async def get_users(**kwargs) -> list:
    return await request('GET', '/data/users', params=kwargs)

Thanks for your help! I was worrying integrating with the API would be a mess, but these precise annotations make it much easier!

LOL

But that’s not quite it. Correct type annotations may not tell the full picture either. Consider this:

class User(TypedDict):
    name: str
    ...
    full_name: NotRequired[str]
    """Only if return_type='full'"""

async def get_users(return_type: Literal['simple', 'full']) -> list[User]:
    ...

Almost there, but not quite… We can narrow it further:

class SimpleUser(TypedDict):
    name: str
    ...

class FullUser(SimpleUser):
    full_name: str

@overload
async def get_users(return_type: Literal['simple']) -> list[SimpleUser]:
    ...
@overload
async def get_users(return_type: Literal['full']) -> list[FullUser]:
    ...

Now we’re talking! Chef kiss.

3. Avoid unnecessary complication

Keep your implementation details to yourself, thank you. Nobody cares about them. Yet how often is one force-fed with this kind of thing?

from sdk.client import Client
from sdk.gateway import ApiGateway
from sdk.transport import HttpClient

client = Client(
    api_gateway=ApiGateway('api3.company.com'),
    transport_client=HttpClient(use_httpx=True),
)

Why?! Why do I have to go through convulsions just to instantiate your damn client? Can’t you pick an HTTP library for me? Can’t you pick an API endpoint? I don’t want to choose, nor care.

No, give me some solid defaults. I should only go through convulsions if I want something really custom:

from sdk import Client

client = Client.new()

And that’s it! If you want, you can optionally give me more options:

# SDK code
class Client:
    @classmethod
    def new(
        cls, *, api_gateway: str = DEFAULT_GATEWAY,
        transport: Literal['httpx', 'requests', 'websockets']
    ):
        return cls(...)

4. Provide extra behavior optionally

You’re writing an API client. Don’t get fancy. I don’t need retry logic, I don’t need an exaggeratedly complicated exception hierarchy. I don’t need the SDK to make me a fucking coffee! Your mission is to make integration easy and type-checkable.

Some examples:

Retries could be great! But make them opt-in:

client = Client.new(retries={
    'max': 5,
    'delay': 2
})

Paging is nice. But not by default:

users = await client.get_users(page=2) # normal, as exposed by the API

async for page in client.get_users_paged(): # okay, as a separate thing
    for user in page:
        ...

Closing

And that’s it. It’s not complicated, just some solid basics. The principles are clear: simplicity, precision and ease of use.