# Tribulnation SDK

> One interface, every venue. Async, fully typed, decimal-precision Python for crypto trading and data.

## Why the SDK?

- **🎯 Swap venues by changing a string**: `Market`, `Wallet`, `Earn` and `Report` are abstract interfaces, so code written against them runs unchanged on every implemented venue, and on several accounts per venue side by side.
- **🛡️ Validated at the edge**: every implementation sits on our [Typed](/typed) clients, so venue responses are typed and validated before they reach you.
- **🔢 No raw primitives**: prices, sizes and fees are `Decimal`, timestamps are `datetime`, never `float` or epoch ints.
- **📊 Beyond trading**: `Report` reads balance and position history from exchanges *and* chains, `Earn` covers yield instruments, `Wallet` covers deposits and withdrawals.

## Installation

```bash
pip install tribulnation-sdk[dydx,hyperliquid,mexc]
```

Extras select which venue packages get installed. See the [support matrix](https://tribulnation.com/sdk/docs/support) for what's actually implemented per venue.

## Quick Start

**1. Define accounts** in `sdk.toml`:

```toml
[accounts.mexc_account1]
venue = "mexc"
api_key = "$MEXC_API_KEY"
api_secret = "$MEXC_API_SECRET"
```

`$VAR` values resolve from the environment, and a missing one fails at load time rather than on first use. Public data needs no entry: `MarketSDK` ships public accounts named `binance`, `bit2me`, `dydx`, `hyperliquid` and `mexc`, and `EarnSDK` ships `bit2me` and `mexc`; an `[accounts.<id>]` table under the same name overrides the default.

Or construct in code: `MarketSDK({'mexc_account1': accounts.Mexc()})` — each `accounts.<Venue>()` field defaults to `$VENUE_FIELD`, e.g. `accounts.Mexc()` reads `$MEXC_API_KEY` and `$MEXC_API_SECRET`.

**2. Trade**:

```python
from tribulnation.sdk import MarketSDK

sdk = MarketSDK.load('sdk.toml')
async with sdk.trades_stream('mexc_account1:spot:BTCUSDT') as my_trades:
  async for my_trade in my_trades:
    print(f'Hedging {my_trade}')
    await sdk.place_order('dydx:perp:BTC-USD', {
      'type': 'LIMIT', 'qty': -my_trade.qty, 'price': my_trade.price
    })
```

You can read more about Market IDs and methods in the [Market](/sdk/docs/market) section.


## Surfaces

- [Market](/sdk/docs/market): trading and market data
- [Earn](/sdk/docs/earn): yield-bearing instruments
- [Wallet](/sdk/docs/wallet): deposit/withdrawal methods
- [Report](/sdk/docs/report): current balances and historical transactions

## Reference

- [Async Usage](/sdk/docs/reference/async-usage): one-shot calls and `async with`
- [Error Handling](/sdk/docs/reference/error-handling): the `Error` hierarchy, shared across venues
- [Context, Logging & Retries](/sdk/docs/reference/context): opt-in logging and retries

## Support Matrix

Not every venue implements every surface yet. See the [support matrix](https://tribulnation.com/sdk/docs/support) for what's actually wired, per venue and per surface.