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.

Standalone gateway

Install tribulnation-sdk[gateway] for tn gateway and the remote ProxySDK. Venue adapters are installed separately on the server. See the gateway guide for configuration, supported operations and migration details.

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

Metadata

Release files for tribulnation-sdk 2.11.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.11.0
File	Size	Uploaded
tribulnation_sdk-2.11.0.tar.gz	67.3 kB	Oct 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for tribulnation-sdk 2.11.0
File	Interpreter	ABI	Platform	Reset
tribulnation_sdk-2.11.0-py3-none-any.whl 91.4 kB Oct 6, 2026	Python 3	none	any	Details

Total release size: 158.7 kB

Release files / tribulnation_sdk-2.11.0.tar.gz

Download URL	tribulnation_sdk-2.11.0.tar.gz
Size	67.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`c04755e1a251361e2126933b466601145b455efaa1806f6e59ad8705d1cd7f08`
BLAKE2b-256 checksum How to use checksums	`7c7e2664290ebbdcc145b2a7905b8de07e4421b9ceef21fd780a4fc2932ba91a`
Upload date	Oct 6, 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/49116ee085514e1f8a34eb92829a391e6433578f

Workflow

Publishing configuration: github.com/tribulnation/sdk/blob/49116ee085514e1f8a34eb92829a391e6433578f/.github/workflows/release.yml
Publishing logs: github.com/tribulnation/sdk/actions/runs/37496744533/attempts/1

Artifact

Subject: tribulnation_sdk-2.11.0.tar.gz
SHA-256 checksum: c04755e1a251361e2126933b466601145b455efaa1806f6e59ad8705d1cd7f08 Verifying attestations

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

Download URL	tribulnation_sdk-2.11.0-py3-none-any.whl
Size	91.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`35536f0e8c355b76b87e1e38b72bdf55b149f9dcd1526316139867183c9f85b6`
BLAKE2b-256 checksum How to use checksums	`7d4ce16617c92add367056c3a77f4408bedf85f1f499fe04a98e18eafbed0812`
Upload date	Oct 6, 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/49116ee085514e1f8a34eb92829a391e6433578f

Workflow

Publishing configuration: github.com/tribulnation/sdk/blob/49116ee085514e1f8a34eb92829a391e6433578f/.github/workflows/release.yml
Publishing logs: github.com/tribulnation/sdk/actions/runs/37496744533/attempts/1

Artifact

Subject: tribulnation_sdk-2.11.0-py3-none-any.whl
SHA-256 checksum: 35536f0e8c355b76b87e1e38b72bdf55b149f9dcd1526316139867183c9f85b6 Verifying attestations