kiwoom_dart

English | 한국어

Dart/Flutter wrapper for Kiwoom Open API REST and WebSocket.

Release Notice

• 0.1.x is the stable REST core release line.
• Validate order-safety and environment settings in a safe environment before production use.

Features

• OAuth token issue/revoke and automatic refresh
• Domain-based typed methods for core domestic stock endpoints
• Raw invoke escape hatch for uncovered endpoints
• Continuation paging helper (cont-yn / next-key)
• Retry and rate-limit handling
• WebSocket realtime connect/login, subscribe/remove, and condition search support
• Order safety guards (dryRun, idempotency key, amount/quantity limits)
• Official-doc provenance attached to each endpoint metadata item
• Metadata manifest/signature verification for cleanroom traceability

Quick Start

import 'dart:io';
import 'package:kiwoom_dart/kiwoom_dart.dart';

final appKey = Platform.environment['KIWOOM_APP_KEY'] ?? '';
final secretKey = Platform.environment['KIWOOM_SECRET_KEY'] ?? '';

final client = KiwoomClient.withCredentials(
  appKey: appKey,
  secretKey: secretKey,
  options: const KiwoomClientOptions(env: KiwoomEnv.mock),
);

final quote = await client.market.getStockQuote(stkCd: '005930');
print(quote.body);

final conditions = await client.realtime.fetchConditionList();
print(conditions.map((item) => item.name).toList());

Development Validation

Run these commands before pushing changes:

dart pub get
dart run tool/verify_official_metadata.dart
dart analyze
dart test

Optional one-command runner:

dart run tool/preflight.dart

Status

• v0.1.x: REST core release
• v0.2.x: REST + WebSocket release line

Realtime Quick Start

final client = KiwoomClient.withCredentials(
  appKey: appKey,
  secretKey: secretKey,
  options: const KiwoomClientOptions(env: KiwoomEnv.mock),
);

await client.realtime.connect();
await client.realtime.register(
  groupNo: '1',
  data: const <KiwoomRealtimeRegistration>[
    KiwoomRealtimeRegistration(
      items: <String>['005930'],
      types: <String>['0B'],
    ),
  ],
);

await for (final event in client.realtime.events) {
  print('event ${event.type} ${event.item} ${event.values}');
  break;
}

Cleanroom Source Policy

• The only specification source is the Kiwoom official API guide:
  • https://openapi.kiwoom.com/m/guide/apiguide?dummyVal=0
• Endpoint metadata includes provenance (source, docUrl, verifiedAt).
• Metadata integrity is verified with:

dart run tool/verify_official_metadata.dart

See doc/cleanroom_policy.md for full policy.