toss-openapi-cli

English | 한국어 | 简体中文 | 日本語

For Agents

If a user gives you this repository link, ask whether they want you to install the CLI and the companion agent skill.

Install the CLI only after the user agrees:

npm install -g toss-openapi-cli

Install the companion skill only after the user agrees:

npx skills add finetension/tosscli-skills -g -a universal

After installing the skill, restart the agent session so the skill is loaded. After installing the CLI, verify tosscli version.

Install

Install the CLI:

npm install -g toss-openapi-cli

Install the companion agent skill globally:

npx skills add finetension/tosscli-skills -g -a universal

Restart your agent session after installing the skill so the new skill is loaded.

Then verify the installed CLI:

tosscli version
tosscli -v
tosscli doctor

toss-openapi-cli is an unofficial, public-OpenAPI-only CLI and agent toolkit for Toss APIs, starting with the Toss Securities Open API exposed through the invest namespace.

The primary command is tosscli. It keeps output structured and predictable so it can be used reliably by automation agents, scripts, and terminal users.

Important

This is not an official Toss or Toss Securities product. It is built against public, documented Open API surfaces and should not be read as endorsed, supported, or maintained by Toss or Toss Securities.

Note

This project does not reuse browser sessions, automate Toss Securities web login, or call undocumented web-internal APIs. It uses documented API contracts instead of browser or undocumented web-app behavior.

Status

This project is in early MVP development. The current implementation focuses on the invest namespace and maps every operation in the bundled OpenAPI spec at specs/invest/openapi.json.

The CLI is designed to stay predictable for automation and comfortable for terminal use:

• JSON-first output on stdout.
• Stable, machine-readable error responses.
• Stable exit codes.
• Commands shaped from official API concepts where practical.
• Order-capable workflows with dry-run support.
• No fallback to browser-session or undocumented web API clients.

See Roadmap for planned public preview and agent usage work.

Why Use This

tosscli provides a local CLI boundary for documented Toss Invest API calls. It keeps credentials, token caching, account headers, request construction, and output formatting in one predictable tool.

Use this project when you want:

• A public OpenAPI-only Toss Invest integration path.
• Agent-readable JSON output and structured JSON errors.
• A CLI boundary for credentials, token caching, account headers, and order request construction.
• Dry-run order previews before any live order request is sent.

This project does not cover Toss Securities web-app features that require browser session reuse or undocumented internal APIs.

Build From Source

go build -o bin/tosscli ./cmd/tosscli
./bin/tosscli version

During development, you can also run commands directly:

go run ./cmd/tosscli version

This repository currently uses Go 1.26.4.

Alternative Install

macOS and Linux can also install from GitHub Releases with the standalone installer:

curl -fsSL https://raw.githubusercontent.com/finetension/toss-openapi-cli/main/install.sh | sh

To install a specific version:

curl -fsSL https://raw.githubusercontent.com/finetension/toss-openapi-cli/main/install.sh | TOSSCLI_VERSION=v0.1.1 sh

The standalone installer defaults to ~/.local/bin. If that directory is not on PATH, follow the printed PATH guidance before running tosscli.

Authentication

The invest API uses OAuth2 client credentials. Run login and enter the credentials interactively:

tosscli invest auth login

You can also provide the same credential names used by the OpenAPI spec as shell environment variables:

export TOSS_INVEST_CLIENT_ID="..."
export TOSS_INVEST_CLIENT_SECRET="..."

Then issue and cache a token without being prompted:

tosscli invest auth login
tosscli invest auth status

Credentials and cached tokens are stored in the OS keyring when possible. tosscli reads process environment variables; it does not automatically load .env files.

You can also pass credentials directly:

tosscli invest auth login \
  --client-id "$TOSS_INVEST_CLIENT_ID" \
  --client-secret "$TOSS_INVEST_CLIENT_SECRET"

For non-interactive environments, an access token can be supplied directly:

export TOSS_INVEST_ACCESS_TOKEN="..."

If login or API calls fail with access_denied and IP address not allowed, check the allowed IP settings for your Toss Open API credentials. The CLI cannot override server-side IP restrictions.

To check the public IP address visible to external services:

tosscli doctor --show-ip

To add an allowed IP:

1. Open https://www.tossinvest.com.
2. Log in.
3. Click the settings button in the bottom-right corner.
4. Open the Open API tab.
5. Click the Add IP button.
6. Enter the IP address and click Add.

Quick Start

Check local readiness:

tosscli doctor

doctor checks only four things: CLI version, credential availability, token availability, and read-only account list access. It does not test order execution.

Check auth and list accounts:

tosscli invest auth status
tosscli invest account list

Read market data:

tosscli invest market-data prices --symbols AAPL
tosscli invest market-data orderbook --symbol AAPL
tosscli invest stock-info stocks --symbols AAPL

Read account state:

ACCOUNT_SEQ="123456789"

tosscli invest asset holdings --account-seq "$ACCOUNT_SEQ"
tosscli invest order-info buying-power --account-seq "$ACCOUNT_SEQ" --currency USD
tosscli invest order-history list --account-seq "$ACCOUNT_SEQ"

Orders

Order commands can place, modify, or cancel real orders. Start with --dry-run to inspect the request without sending it to Toss Invest.

tosscli invest order create \
  --dry-run \
  --account-seq "$ACCOUNT_SEQ" \
  --symbol AAPL \
  --side BUY \
  --order-type LIMIT \
  --quantity 1 \
  --price 100

Remove --dry-run only when you intend to send the order:

tosscli invest order create \
  --account-seq "$ACCOUNT_SEQ" \
  --symbol AAPL \
  --side BUY \
  --order-type LIMIT \
  --quantity 1 \
  --price 100

Modify or cancel an order:

tosscli invest order modify "$ORDER_ID" \
  --dry-run \
  --account-seq "$ACCOUNT_SEQ" \
  --quantity 1 \
  --price 101

tosscli invest order cancel "$ORDER_ID" \
  --dry-run \
  --account-seq "$ACCOUNT_SEQ"

Output Contract

Successful commands print formatted JSON to stdout. Where practical, the CLI preserves the Toss Invest API response shape instead of wrapping every response in a custom envelope.

Errors are also JSON:

{
  "error": {
    "code": "AUTH_CONFIG_ERROR",
    "message": "Toss Invest credentials are not configured",
    "reason": "AUTH_CONFIG_ERROR"
  }
}

Exit codes:

Code	Meaning
0	Success
1	Unexpected CLI error
2	Usage error
3	Authentication or configuration error
4	Toss Invest API error
5	Spec or generated-surface error

Commands

Diagnostics:

tosscli doctor

Authentication:

tosscli invest auth login
tosscli invest auth status
tosscli invest auth token
tosscli invest auth logout

Accounts and assets:

tosscli invest account list
tosscli invest asset holdings

Market data:

tosscli invest market-data prices
tosscli invest market-data orderbook
tosscli invest market-data trades
tosscli invest market-data price-limits
tosscli invest market-data candles

Market and stock information:

tosscli invest stock-info stocks
tosscli invest stock-info warnings <symbol>
tosscli invest market-info exchange-rate
tosscli invest market-info calendar kr
tosscli invest market-info calendar us

Order information and history:

tosscli invest order-info buying-power
tosscli invest order-info sellable-quantity
tosscli invest order-info commissions
tosscli invest order-history list
tosscli invest order-history get <orderId>

Order mutations:

tosscli invest order create
tosscli invest order modify <orderId>
tosscli invest order cancel <orderId>

Use --help on any command to see required flags:

tosscli invest order create --help

Inspect the full command help surface:

tosscli help --all
tosscli help --all --json

Development

Run the test suite:

go test ./...

Build the CLI:

go build -o bin/tosscli ./cmd/tosscli

Check the release configuration:

goreleaser check

Create local snapshot artifacts:

goreleaser release --snapshot --clean

Release

Public releases are published through GitHub Releases and GoReleaser:

• Cross-platform archives for macOS, Linux, and Windows.
• SHA256 checksums.
• install.sh for macOS/Linux.
• Windows zip first, with install.ps1 after manual Windows validation.

Create the next version tag:

scripts/version.sh patch
scripts/version.sh minor
scripts/version.sh major

The script runs the local pre-release checks, validates GoReleaser configuration, and creates the local tag. A specific version can also be passed, for example scripts/version.sh 0.1.10.

Push the created tag to start the release workflow:

git push origin v0.1.10

Homebrew, Scoop, Winget, npm wrappers, signing, and notarization are intentionally deferred until the GitHub Releases path is stable.

Disclaimer

This project is unofficial and provided as-is. Trading APIs can move real money and may create financial loss. Review commands, credentials, account numbers, symbols, quantities, prices, and order status before sending mutation requests.