openapi-rs-sdk
Real gRPC + protobuf trading SDK in Rust with a broker-forwarding adapter server.
Features
- Symbol metadata registry (
contract_size, min/max lot, step) - Lot-size-only volume quoting (
symbol + lot_size -> volume) - Auth flow (
register_user,login,logout) - Account flow (
fetch_balance,fetch_open_positions) - Trading flow (
place_market_order) - Protobuf contract and generated tonic server/client types
- Async SDK client wrapper (
OpenApiSdkClient)
Cargo Feature Modes
backtest: local in-memory engine + gRPC service for simulation/replay flowslive: broker-forwarding gRPC adapter (BrokerGrpcAdapterServer)demo: Spotware demo adapter (SpotwareGrpcAdapterServer); implieslivefull: enables all modes above (default)
Build examples:
# backtest only
# live broker-proxy only
# spotware demo adapter (includes live)
# all modes (default)
Project Layout
proto/openapi.proto: protobuf contractbuild.rs: tonic/prost code generation at build timesrc/lib.rs: domain engine, service logic, gRPC server adapter, SDK clientexamples/grpc_server.rs: runnable local serverexamples/grpc_client.rs: runnable local client
Requirements
- Rust stable (edition 2024)
- Cargo
Quick Start
- Run tests:
- Start broker adapter server:
BROKER_OPENAPI_GRPC_URL=http://<broker-host>:<broker-port> cargo
- In another terminal, run SDK client:
OPENAPI_GRPC_URL=http://127.0.0.1:50051
You should see quote, order execution, open positions, and balance output.
SDK Client Usage
use ;
use Decimal;
async
API Surface
Domain Engine
OpenApiEngine::register_symbolOpenApiEngine::volume_from_lot_sizeOpenApiEngine::quote_volume_proto
Service Logic
OpenApiService::register_userOpenApiService::loginOpenApiService::logoutOpenApiService::fetch_balanceOpenApiService::fetch_open_positionsOpenApiService::place_market_order
gRPC Transport
- Server adapter:
OpenApiGrpcServer - Broker proxy adapter:
BrokerGrpcAdapterServer - Generated tonic service trait:
pb::open_api_service_server::OpenApiService - SDK client wrapper:
OpenApiSdkClient
Symbol and Lot Rules
For each symbol, configure:
contract_sizemin_lotmax_lotlot_step
Validation rules:
lot_size > 0min_lot <= lot_size <= max_lot(lot_size - min_lot) % lot_step == 0
If symbol is missing, API returns not-found.
Protobuf Notes
- Proto file:
proto/openapi.proto - Decimal numbers are represented as strings in protobuf messages
- Order side values:
ORDER_SIDE_UNSPECIFIEDORDER_SIDE_BUYORDER_SIDE_SELL
Error Mapping
Domain errors map to gRPC status codes in server adapter:
SymbolNotFound->not_foundInvalidCredentials,SessionNotFound->unauthenticatedUserAlreadyExists,AccountAlreadyExists->already_existsInsufficientMargin->failed_precondition- validation failures ->
invalid_argument
Generate Docs
Build Rust API docs:
Publish To crates.io
- Ensure your crate name is available:
- Package validation:
- Login and publish:
- Release updates:
- bump version in
Cargo.toml - tag in git (recommended)
- run
cargo publishagain
Use In Other Projects
From crates.io (recommended)
After publishing, in another Rust project:
or in Cargo.toml:
[]
= "0.1"
Directly from GitHub (before first publish)
[]
= { = "https://github.com/elsadeny/openapi-rs", = "v0.1.0" }
You can also pin a commit:
[]
= { = "https://github.com/elsadeny/openapi-rs", = "<commit-sha>" }
```rust
{OpenApiSdkClient, OrderSide};
## Production Notes
- `examples/grpc_server.rs` is a broker-forwarding adapter and does not run local simulator state
- Set `BROKER_OPENAPI_GRPC_URL` to your broker OpenAPI gRPC endpoint
- Set your bot/client `OPENAPI_GRPC_URL` to the adapter endpoint
## Tiny Broker Smoke Test
Run the live smoke test (ignored by default) against your broker-connected adapter:
```bash
OPENAPI_GRPC_URL=http://127.0.0.1:50051 \
OPENAPI_USERNAME=<broker-user> \
OPENAPI_PASSWORD=<broker-pass> \
OPENAPI_SMOKE_SYMBOL=EURUSD \
cargo test --test broker_smoke -- --ignored --nocapture
The smoke flow performs:
- login
- place market order (
0.01sell) - fetch balance
- fetch open positions
For broker platform confirmation, match the returned order_id/position on your broker UI or terminal.