Tribulnation SDK

Fully-typed, async Python SDK for crypto trading and data.

Market, Wallet, Earn, and Report are abstract interfaces implemented per exchange and chain. Code written against MarketSDK runs unchanged on dYdX, Hyperliquid, MEXC, or any other supported venue.

Installation

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

See the support matrix for details on extras.

Trading Quick Start

from dotenv import load_dotenv
from tribulnation.sdk import MarketSDK, accounts

load_dotenv()  # load credentials from .env file

sdk = MarketSDK(
  {
    'mexc_account1': accounts.Mexc(
      api_key='$MEXC_API_KEY', api_secret='$MEXC_API_SECRET'
    ),
    # 'dydx', 'hyperliquid', and 'mexc' are available by default, even without listing them here
  }
)
mexc = await sdk.market('mexc_account1:spot:BTCUSDT')
dydx = await sdk.market('dydx:perp:BTC-USD')

async with mexc.trades_stream() as my_trades:
  async for my_trade in my_trades:
    print(f'Hedging {my_trade}')
    await dydx.place_order(
      {
        'type': 'LIMIT',
        'qty': -my_trade.qty,
        'price': my_trade.price,
      }
    )

accounts.<Venue>() reads credentials from environment variables named after each field (accounts.Mexc() reads $MEXC_API_KEY/$MEXC_API_SECRET) — pass explicit values or other $VAR names to override.

Market IDs & Scoping

<account_id>:<exchange_id>:<market_id>, e.g. mexc_account1:spot:BTCUSDT. account_id is the key you registered in accounts — not necessarily the venue's own name — so you can run several accounts on one venue side by side. Equivalent ways to reach a market:

await sdk.depth('mexc_account1:spot:BTCUSDT')

venue = await sdk.venue('mexc_account1')
await venue.depth('spot:BTCUSDT')

exchange = await venue.exchange('spot')
await exchange.depth('BTCUSDT')

market = await exchange.market('BTCUSDT')
await market.depth()

Hold a Market reference in hot loops; use the scoped one-shot calls otherwise.

Market Interface

Public data:
- depth() -> Book
- depth_stream() -> AsyncContextManager[AsyncIterable[Book]]
- rules() -> Rules: tick/step size, fees, min/max, rounding helpers
- candles(interval, start, end) -> PaginatedResponse[Candle]: trade candles opening in [start, end), with timezone-aware bounds and no ordering guarantee; CANDLE_INTERVALS says which widths a venue serves
User data:
- query_order(id) -> OrderState | None
- open_orders() -> Sequence[OrderState]
- trades_history(start, end) -> AsyncIterable[Sequence[Trade]]
- trades_stream() -> AsyncContextManager[AsyncIterable[Trade]]
- position() -> Position
- available_notional() -> Decimal: max. notional you could open now
Trading:
- place_order(order) -> OrderResponse
- place_orders(orders) -> Sequence[OrderResponse]
- cancel_order(id)
- cancel_orders(ids)
- cancel_open_orders()
Perpetual markets:
- index() -> Decimal
- next_funding() -> FundingRate
- funding_rates(start, end=None) -> AsyncIterable[Sequence[FundingRate]]: market-wide rate history
- funding_payments(start, end) -> AsyncIterable[Sequence[FundingPayment]]: your own settled cashflows
- perp_position() -> PerpPosition: includes entry price

Full reference: docs/market/index.md, with per-venue notes for dYdX, Hyperliquid, and MEXC.

Mutating methods also take an optional settings dict for venue-specific options, keyed by venue:

await dydx.place_order(
  {
    'type': 'LIMIT',
    'qty': 0.01,
    'price': 60_000,
  },
  settings={'dydx': {'order_flags': 'SHORT_TERM', 'short_term_gtb': 2}},
)

Other SDKs

Same account-mapping shape as MarketSDK:

WalletSDK: deposit/withdrawal methods — docs/wallet.md
EarnSDK: yield instruments — docs/earn.md
ReportSDK: balance/position history, with provenance — docs/report.md

Every SDK object is an async context manager: call methods on it directly, or enter it with async with to close its connections at a point you choose. Details: Async Usage.

Error Handling

All errors subclass Error: NetworkError, ValidationError, ApiError (BadRequest, AuthError, RateLimited), LogicError.

Context, Logging & Retries

SDK calls are plain by default — no logging, no retries. Wrap them in a Context to add both:

from tribulnation.sdk import Context, NetworkError, RateLimited

ctx = Context().retried(NetworkError, RateLimited, max_retries=5).logged()
with ctx.use():
  await sdk.place_order(
    'mexc_account1:spot:BTCUSDT', {'type': 'LIMIT', 'qty': 0.01, 'price': 60_000}
  )

Retries back off exponentially and only wrap plain async calls, not streams or paginated history. Nested SDK calls each re-apply the active context, so retries can compound across scoping layers. Details: Context, Logging & Retries.

License

MIT

Release files for tribulnation-sdk 2.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tribulnation-sdk 2.3.0
File	Size	Uploaded
tribulnation_sdk-2.3.0.tar.gz	51.6 kB	Sep 20, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for tribulnation-sdk 2.3.0
File	Interpreter	ABI	Platform	Reset
tribulnation_sdk-2.3.0-py3-none-any.whl 72.6 kB Sep 20, 2026	Python 3	none	any	Details

Total release size: 124.3 kB

Release files / tribulnation_sdk-2.3.0.tar.gz

Download URL	tribulnation_sdk-2.3.0.tar.gz
Size	51.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`2fa5b7860bae088a3232d1f469b094e087673efa5b112be7e6218256ef0e26ae`
BLAKE2b-256 checksum How to use checksums	`f2c0b8d650eaa8132de065ffdc47ca93cb18d2471c280fc4f0f3d09900192bc4`
Upload date	Sep 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/tribulnation/sdk
Publishing commit: github.com/tribulnation/sdk/tree/7700bf005c0a5ca7e4ae09e5920d3863f77b30c2

Workflow

Publishing configuration: github.com/tribulnation/sdk/blob/7700bf005c0a5ca7e4ae09e5920d3863f77b30c2/.github/workflows/release.yml
Publishing logs: github.com/tribulnation/sdk/actions/runs/35499495321/attempts/1

Artifact

Subject: tribulnation_sdk-2.3.0.tar.gz
SHA-256 checksum: 2fa5b7860bae088a3232d1f469b094e087673efa5b112be7e6218256ef0e26ae Verifying attestations

Release files / tribulnation_sdk-2.3.0-py3-none-any.whl

Download URL	tribulnation_sdk-2.3.0-py3-none-any.whl
Size	72.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`cc0c9698ad966983add9b418757ad8e2e4768fb5e85bb50de488b7901bb701ae`
BLAKE2b-256 checksum How to use checksums	`714487f8d03560480820b8ca122579b89868affdeee0c1293c18c4b3e2455419`
Upload date	Sep 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/tribulnation/sdk
Publishing commit: github.com/tribulnation/sdk/tree/7700bf005c0a5ca7e4ae09e5920d3863f77b30c2

Workflow

Publishing configuration: github.com/tribulnation/sdk/blob/7700bf005c0a5ca7e4ae09e5920d3863f77b30c2/.github/workflows/release.yml
Publishing logs: github.com/tribulnation/sdk/actions/runs/35499495321/attempts/1

Artifact

Subject: tribulnation_sdk-2.3.0-py3-none-any.whl
SHA-256 checksum: cc0c9698ad966983add9b418757ad8e2e4768fb5e85bb50de488b7901bb701ae Verifying attestations