tbank_invest_grpc 0.1.1

Dart gRPC client for T-Invest API (T-Bank) with generated protobuf models for every service and Decimal support for Quotation/MoneyValue.

tbank_invest_grpc

A Dart gRPC client for the T-Invest API — T-Bank's brokerage API (formerly Tinkoff Invest API). The package bundles generated protobuf/gRPC models for every API service, a ready-to-use client, and helper extension methods for working with money and quotations.

Features

• Ready-made clients for every API service: UsersServiceClient, InstrumentsServiceClient, MarketDataServiceClient (plus its streaming variant), OperationsServiceClient (plus its streaming variant), OrdersServiceClient (plus its streaming variant), SandboxServiceClient, SignalServiceClient, StopOrdersServiceClient.
• A single entry point, InvestClient, which picks the right transport automatically: a native HTTP/2 gRPC channel on the VM/Flutter native platforms, and gRPC-Web in the browser (see gRPC-Web caveats below — it needs a proxy).
• Trusts the Russian Trusted CA out of the box — invest-public-api.tbank.ru's certificate chains to a root run by Russia's Ministry of Digital Development, which most trust stores outside Russia don't ship. Disable this with trustRussianCa: false if needed.
• Support for both production and sandbox environments (InvestEnvironment).
• toDecimal() / toQuotation() / toMoneyValue() extension methods to convert Quotation and MoneyValue (a units + nano pair) to and from Decimal without losing precision.

Getting started

Add the dependency:

dependencies:
  tbank_invest_grpc: ^0.1.0

Get an access token from the T-Invest personal account (you can also issue a sandbox-only token there by selecting the "Sandbox" type).

Usage

import 'dart:io';

import 'package:tbank_invest_grpc/tbank_invest_grpc.dart';

void main() async {
  final token = Platform.environment['TINVEST_TOKEN']!;
  final client = InvestClient(token);

  final accounts = await client.users.getAccounts(GetAccountsRequest());
  print('Accounts found: ${accounts.accounts.length}');
}

Connecting to the sandbox:

final client = InvestClient(
  token,
  environment: InvestEnvironment.sandbox,
);

Working with money and quotations via Decimal:

import 'package:decimal/decimal.dart';
import 'package:tbank_invest_grpc/tbank_invest_grpc.dart';

final response = await client.marketData.getLastPrices(GetLastPricesRequest());
final price = response.lastPrices.first.price.toDecimal(); // Decimal, no precision loss

final order = PostOrderRequest(
  price: Decimal.parse('123.45').toQuotation(),
  // ...
);

See a full working example in example/tbank_invest_grpc_example.dart.

gRPC-Web caveats

The browser transport is real gRPC-Web (via package:grpc's GrpcWebClientChannel), but two things are worth knowing before relying on it:

• invest-public-api.tbank.ru can't be reached directly from a browser. It's a plain gRPC (HTTP/2) endpoint — it doesn't speak the grpc-web wire protocol or send CORS headers, so every browser request fails before any application-level response comes back (test/web_smoke_test.dart pins this down). To use this client from the browser, run your own grpc-web proxy (e.g. Envoy) in front of the API and pass its host via InvestClient(token, host: 'your-proxy-host').
• Client-streaming and bidirectional-streaming calls don't work over gRPC-Web at all — that's a protocol limitation, not something a proxy can fix. Of this package's services, only MarketDataStreamService.MarketDataStream (client.marketDataStream.marketDataStream) is bidirectional; every other streaming method is server-streaming only and works fine over gRPC-Web.

Service reference

doc/services/ has one Markdown page per gRPC service (methods, request/response types, and the upstream doc comments) — see the index.

Maintenance scripts

tool/ contains scripts to keep the package up to date:

• dart run tool/refetch_protos.dart — downloads the latest .proto files from the official investAPI repository.
• dart run tool/regenerate_protos.dart — regenerates Dart bindings from the .proto files.
• dart run tool/refresh_russian_ca.dart — refreshes the bundled Russian Trusted CA.
• dart run tool/generate_docs.dart — generates static API documentation into doc/api/ via dart doc (not committed; pub.dev builds this automatically on publish).
• dart run tool/generate_service_docs.dart — regenerates doc/services/ from the .proto contracts.

Testing

Three test files make real network calls and are tagged network; skip them when offline or in a sandboxed CI runner:

dart test -x network

• test/russian_trusted_ca_test.dart connects to invest-public-api.tbank.ru to verify the bundled CA is actually trusted (and that the handshake fails without it). Needs no token.

• test/sandbox_test.dart exercises a full account lifecycle against the sandbox environment: opens an account, pays in funds, reads the balance back as a Decimal, and closes the account. Needs a sandbox token:

  TINVEST_SANDBOX_TOKEN=<your sandbox token> dart test test/sandbox_test.dart
  

  Without the variable set, this test is skipped rather than failing.

• test/web_smoke_test.dart pins down the gRPC-Web CORS limitation described above. It only runs in an actual browser, so it's excluded from the default dart test run — use:

  dart test -p chrome test/web_smoke_test.dart
  

CI

.github/workflows/ci.yml runs on every push and pull request: dart format/dart analyze, the offline test suite, the network suite against the sandbox (using a TINVEST_SANDBOX_TOKEN repository secret), and the Chrome smoke test.

Additional information

This package is not affiliated with T-Bank and is not an official SDK — it's an independent wrapper around the public gRPC API. See developer.tbank.ru/invest for the official API documentation.

The .proto contracts under proto/ are vendored from T-Bank's investAPI repository, except for proto/google/api/field_behavior.proto, which is Copyright 2023 Google LLC and licensed separately under Apache License 2.0 — this package's own MIT license (see LICENSE) applies to the Dart source only.

Report bugs and suggestions via the repository's issues. See CONTRIBUTING.md for how to contribute, SECURITY.md for reporting vulnerabilities, and CODE_OF_CONDUCT.md for community expectations.