Limeint Trade API — Python SDK

Limeint's Python SDK for the gRPC Trade API. It wraps the generated stubs with:

• a single TradeAPIClient / AsyncTradeAPIClient entry point,
• automatic JWT issuance and background refresh (via AuthService.SubscribeJwtRenewal),
• a from_rpc_error() helper for typed errors,
• exponential-backoff retries for UNAVAILABLE and server-approved rate-limit retries.

Service methods are invoked directly on the generated stubs, without an extra request or response translation layer.

Installation

Python 3.10 or newer is required.

This checkout currently targets 2.18.2, which is on PyPI. Create and activate a virtual environment, then install it:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install limeint-sdk==2.18.2

The PyPI distribution is limeint-sdk; the Python import name is trade_api.

Quick start

The first program authenticates and prints the account IDs visible to the secret. It is bounded and does not place an order.

Save this as quickstart.py:

import os

from trade_api import TradeAPIClient
from trade_api.auth_messages import TokenDetailsRequest


secret = os.environ["TRADE_API_SECRET"]

with TradeAPIClient(secret=secret) as client:
    token = client.get_token()
    if token is None:
        raise RuntimeError("Authentication did not return a token")

    details = client.auth.TokenDetails(TokenDetailsRequest(token=token))
    print("Available account IDs:", list(details.account_ids))

Run it inside the activated virtual environment:

TRADE_API_SECRET=... python quickstart.py

If authentication fails, confirm that the secret is active. An empty account list means the token does not expose a trading account; it may still be usable for market data if it has the required entitlement.

To fetch one of the discovered accounts, extend the program like this:

import os

from trade_api import TradeAPIClient
from trade_api.accounts import GetAccountRequest
from trade_api.auth_messages import TokenDetailsRequest


with TradeAPIClient(secret=os.environ["TRADE_API_SECRET"]) as client:
    token = client.get_token()
    if token is None:
        raise RuntimeError("Authentication did not return a token")

    details = client.auth.TokenDetails(TokenDetailsRequest(token=token))
    if not details.account_ids:
        raise RuntimeError("This secret exposes no accounts")

    account_id = details.account_ids[0]
    account = client.accounts.GetAccount(GetAccountRequest(account_id=account_id))
    print(account)

Asyncio quick start

import asyncio
import os

from trade_api import AsyncTradeAPIClient
from trade_api.auth_messages import TokenDetailsRequest


async def main() -> None:
    async with AsyncTradeAPIClient(secret=os.environ["TRADE_API_SECRET"]) as client:
        token = client.get_token()
        if token is None:
            raise RuntimeError("Authentication did not return a token")

        details = await client.auth.TokenDetails(TokenDetailsRequest(token=token))
        print("Available account IDs:", list(details.account_ids))


asyncio.run(main())

Subscribe to market data

Streaming RPCs return iterators. This synchronous example runs until Ctrl-C; leaving the context manager closes the channel and token-renewal stream:

import os

from trade_api import TradeAPIClient
from trade_api.market_data import SubscribeQuoteRequest


with TradeAPIClient(secret=os.environ["TRADE_API_SECRET"]) as client:
    for tick in client.market_data.SubscribeQuote(
        SubscribeQuoteRequest(symbols=["AAPL@XNAS"])
    ):
        print(tick)

The repository also includes focused examples for authentication and accounts, async quote streaming, and real order placement with cancellation. They live in a standalone consumer project that installs the published package by default.

Available services

The client currently exposes these Trade API services as sub-clients:

The protobuf contracts also contain CorporateActionsService, but the current Python client does not yet expose it as a sub-client. The Node.js SDK does.

API reference

Every RPC belonging to the services listed below is exposed directly on its sub-client. Request and response message types are re-exported from short, per-service modules:

The original deeply-nested paths (trade_api.proto.grpc.tradeapi.v1.<service>.<service>_service_pb2) still work and remain the source of truth.

Legend: ▶ unary · ⇉ server-stream · ⇄ bidi-stream

client.auth — AuthService

client.accounts — AccountsService

client.assets — AssetsService

client.market_data — MarketDataService

client.orders — OrdersService

client.reports — ReportsService

client.metrics — UsageMetricsService

Client lifecycle

for_testing(...) opens an insecure (plaintext) channel against an in-process fake server. Never use against api.limeint.eu — it sends your JWT in clear.

Error handling

SDK calls raise raw grpc.RpcError instances. Use from_rpc_error() when your application benefits from the SDK's typed TradeAPIError hierarchy:

import grpc
from trade_api import TradeAPIClient, RateLimitError, from_rpc_error

with TradeAPIClient(secret="...") as client:
    try:
        client.accounts.GetAccount(GetAccountRequest(account_id="A12345"))
    except grpc.RpcError as raw:
        err = from_rpc_error(raw)
        if isinstance(err, RateLimitError):
            ...
        raise err

Exception classes: AuthError (401), PermissionDeniedError (403), InvalidArgumentError (400), NotFoundError (404), RateLimitError (429), InternalError (500), ServiceUnavailableError (503), DeadlineExceededError (504). All inherit from TradeAPIError.

Retries

Unary RPCs retry UNAVAILABLE automatically with exponential backoff and jitter. RESOURCE_EXHAUSTED is retried only when the server supplies grpc-retry-pushback-ms; otherwise the SDK returns the rate-limit error instead of amplifying the throttle. Streaming RPCs are not retried — the caller is expected to reconnect at a meaningful boundary, such as the last received bar.

Override the policy:

from trade_api import TradeAPIClient, RetryPolicy

policy = RetryPolicy(max_attempts=6, initial_backoff=0.5, max_backoff=10.0)
client = TradeAPIClient(secret="...", retry_policy=policy)

Local build

From the repository root:

cd sdk/python
uv sync --locked
uv run ./scripts/generate_proto.sh
uv run ruff check trade_api tests
uv run mypy trade_api
uv run pytest

scripts/generate_proto.sh compiles the .proto files in ../../proto/ into trade_api/proto/. Re-run it whenever the protos change.

Layout

sdk/python/
├── pyproject.toml
├── uv.lock
├── README.md
├── LICENSE
├── scripts/
│   └── generate_proto.sh      # protoc invocation (contributors only)
└── trade_api/
    ├── __init__.py
    ├── client.py               # TradeAPIClient (sync)
    ├── aio.py                  # AsyncTradeAPIClient
    ├── auth.py                 # JWT lifecycle
    ├── retry.py                # retry policy + interceptors
    ├── exceptions.py           # typed errors
    ├── _insecure_auth.py       # plaintext test-channel authentication
    ├── _metadata.py            # Authorization header plumbing
    ├── _services.py            # lazy generated-service registry
    ├── accounts.py             # message re-exports (per-service)
    ├── assets.py
    ├── auth_messages.py
    ├── market_data.py
    ├── orders.py
    ├── reports.py
    ├── metrics.py
    └── proto/                  # generated by CI; ships in wheel and sdist