J-Quants CLI Usage Guide

Role & Decision Flow

When building jquants commands, make judgments in the following order:

Determine data type — Equities (eq), Market (mkt), Derivatives (deriv), Finance (fins), Index (idx)
Check plan restrictions — Confirm whether it is available under the user's plan (refer to "Subscription Plans & API Availability" below). If the plan is unknown, present the command and clearly state the required plan
Check field names — Before filtering with
```
-f
```
, check the exact name with
```
jquants schema <endpoint>
```
(do not guess)
Choose between individual API and bulk — If it falls into any of "all tickers", "over 1 month", "large volume" → Use bulk (refer to references/commands-bulk.md). Repeated calls to individual APIs in large quantities will hit rate limits (refer to Rate Limits below). Free plan does not support CSV/bulk download (except
```
mkt calendar
```
)
Assemble the command — Place global options (
```
--output
```
,
```
--save
```
,
```
-f
```
) before subcommands
Consider pipes — If there is a pipe destination, just omit
```
--output
```
and CSV will be streamed automatically

Prerequisites

Recommended: Log in via browser with
jquants login
(API key is automatically obtained and saved)

jquants login   # Browser opens, log in with Cognito OAuth2 PKCE
                # → API key is automatically saved to ~/.config/jquants/credentials.json

Fallback: Specify directly via environment variables

export JQUANTS_API_KEY="your-api-key"
# Or write it in the .env file

Authentication priority: api_key in

~/.config/jquants/credentials.json

→

JQUANTS_API_KEY

environment variable → Error (prompt to run

jquants login

)

jquants schema
does not require authentication. It can be used to check field names even before logging in.

Command Syntax Rules

Global options (
--output
,
--save
,
-f
) must be placed before subcommands:

# ✅ Correct
jquants --output csv --save out.csv eq daily --code 86970

# ❌ Incorrect (invalid after subcommand)
jquants eq daily --code 86970 --output csv

Reason: Due to clap's design, flags after a subcommand are parsed as options of the subcommand itself. Placing them after the subcommand will cause an "unknown flag" error.

Automatic CSV switching when piping:

When stdout is not a TTY (when there is a pipe destination), the default

--output table

will automatically output in CSV format.

# Automatically streams CSV when piped
jquants eq daily --code 86970 | head -5

# Explicit specification is required if you want to pipe JSON
jquants --output json eq daily --code 86970 | jq '.[] | .AdjustmentClose'

Filter columns with field selection (
--fields
/
-f
):

# Get only date, code, adjusted close price
jquants -f Date,Code,AdjustmentClose eq daily --code 86970

# If an invalid field name is specified, an error will be displayed with a list of available fields

Schema-First: Check field names

Before filtering columns with

--fields

, confirm the exact field name with

jquants schema <endpoint>

. Do not guess field names (most are PascalCase, but there may be inconsistencies).

jquants schema                  # List of all endpoints (key, description, number of fields)
jquants schema eq.daily         # All fields of eq.daily (name, type, description)
jquants --output json schema    # Output in JSON format

Endpoint keys are in the format

category.command

(e.g.

eq.daily

fins.summary

mkt.short-ratio

Steps:

Get the list of fields with
```
jquants schema eq.daily
```
Copy the required field names and specify them with
```
-f
```
Invalid field names will be rejected with an error (list of available fields will be displayed)

Quick Reference

Authentication & Utilities

What you want to do	Command
Log in (first time setup)	`jquants login`
Log out	`jquants logout`
Check API field list	`jquants schema`
Field details for specific endpoint	`jquants schema eq.daily`

Equities Data (eq)

What you want to do	Command	Update Time
All ticker master	`jquants eq master`	Around 17:30 daily
Stock price OHLCV	`jquants eq daily`	Around 16:30 daily
Morning session OHLCV	`jquants eq am`	Around 12:00 daily
Minute bar data	`jquants eq minute`	Around 16:30 daily
Trading status by investor sector	`jquants eq investor-types`	Weekly (Thursday) around 18:00
Earnings announcement scheduled date	`jquants eq earnings-calendar`	Irregular around 19:00
Stock price tick data	`jquants eq trades`	Around 16:30 daily

Market Data (mkt)

What you want to do	Command	Update Time
Trading breakdown	`jquants mkt breakdown`	Around 18:00 daily
Daily published margin balance	`jquants mkt margin-alert`	Around 16:30 daily
Weekend margin balance	`jquants mkt margin-interest`	Weekly (Tuesday) around 16:30
Trading calendar	`jquants mkt calendar`	Irregular
Short selling ratio by industry	`jquants mkt short-ratio`	Around 16:30 daily
Short selling balance report	`jquants mkt short-sale-report`	Around 17:30 daily

Derivatives (deriv)

What you want to do	Command	Update Time
Futures OHLCV	`jquants deriv futures`	Around 27:00 daily
Options OHLCV	`jquants deriv options`	Around 27:00 daily
Nikkei 225 options	`jquants deriv options-225`	Around 27:00 daily

Financial Data (fins)

What you want to do	Command	Update Time
Financial statements	`jquants fins details`	Around 18:00 daily (flash) / around 24:30 (final)
Dividend information	`jquants fins dividend`	Around 12:00~19:00 daily
Financial information summary	`jquants fins summary`	Around 18:00 daily (flash) / around 24:30 (final)

Index Data (idx)

What you want to do	Command	Update Time
TOPIX index OHLCV	`jquants idx daily-topix`	Around 16:30 daily
Index OHLCV	`jquants idx daily`	Around 16:30 daily

Category Reference Files

Detailed command syntax, flags and examples for each category are described in the reference files. If the information in Quick Reference is sufficient, you do not need to read the references.

Refer to the references in the following cases:

Category	Reference	Scenarios to refer
eq	references/commands-eq.md	Ticker code/date/period filters, special behavior of `eq trades`
mkt	references/commands-mkt.md	Special flags such as `--s33` , `--disc-date` / `--calc-date`
deriv	references/commands-deriv.md	Usage of `--category` , `--contract-flag`
fins	references/commands-fins.md	FS field of `fins details` (JSON output required)
idx	references/commands-idx.md	Index code specification, TOPIX
bulk	references/commands-bulk.md	Judgment criteria, workflow, endpoint list for bulk download
plans	references/plans.md	API availability, obtainable period, add-on information by plan
schedule	references/data-update-schedule.md	When you need data freshness judgment, detailed update timing, scenario-based judgment examples

Output, Fields, and Save

# Output formats: table (default), json, csv, parquet
jquants --output json eq master
jquants --output csv eq master
jquants --output parquet --save master.parquet eq master   # --save is required for Parquet

# Save file (--save cannot be used with --output table)
jquants --output csv --save master.csv eq master
jquants --output json --save daily.json eq daily --code 86970

# Field selection: filter columns with -f (valid for all formats)
jquants -f Date,Code,AdjustmentClose eq daily --code 86970
jquants --output csv -f Date,Code,AdjustmentClose --save daily.csv eq daily --code 86970

# Process data with pipes
jquants eq daily --code 86970 | head -5                         # Automatic CSV
jquants --output json eq daily --code 86970 | jq '.[0]'        # Explicit JSON

Workflow Recipes

Stock price trend analysis for specific ticker

# 1. Confirm ticker code
jquants eq master --code 72030

# 2. Confirm field names
jquants schema eq.daily

# 3. Save daily data for the past 3 months as CSV
jquants --output csv --save toyota.csv \
  -f Date,AdjustmentClose,Volume \
  eq daily --code 72030 --from 2026-01-01 --to 2026-03-31

Obtain monthly data for all tickers (bulk)

# Do not loop with individual APIs. Use bulk for all tickers.
jquants bulk get --endpoint /equities/bars/daily --date 2026-03 --download

# Decompress and use as CSV
gunzip *.gz

Obtain financial information

# Dividend information (period specified)
jquants --output csv --save div.csv fins dividend --from 2026-01-01 --to 2026-03-31

# Financial summary (ticker specified, JSON recommended)
jquants --output json fins summary --code 86970

# Complete financial statement data (JSON required for FS field)
jquants --output json fins details --code 86970

Special Behaviors

eq trades uses bulk API internally

Unlike other

eq

commands,

eq trades

internally calls the bulk API of

/equities/trades

. Therefore:

```
--code
```
flag is not available
Month specification in
```
--date YYYY-MM
```
format is supported (different from
```
YYYY-MM-DD
```
for individual APIs)
Save files to current directory with
```
--download
```
flag

jquants eq trades --date 2025-12             # Get URL only
jquants eq trades --date 2025-12 --download  # Download file

FS field of fins details

The FS (Financial Statement) field of

fins details

is a nested JSON object. It is abbreviated as

"N items"

in table view. Use
--output json
to get complete data.

--contract-flag of deriv

--contract-flag 1

only gets the front month (the most actively traded contract month). If omitted, data for all contract months will be returned. Available for both

deriv futures

and

deriv options

Rate Limits

J-Quants API has a request limit per minute for each plan. Design commands with the limit in mind to avoid unnecessary blocking.

Limit by plan (requests/minute)

Plan	Limit
Free	5
Light	60
Standard	120
Premium	500

Limit by add-on (applied independently of the plan)

Add-on	Limit
Stock minute bar/tick data	60

Behavior when limit is exceeded

HTTP
```
429 Too Many Requests
```
is returned
If the limit is significantly exceeded continuously, access will be completely blocked for about 5 minutes (immediate retry is counterproductive)

Avoidance tips

Do not use individual loops for all tickers × all dates — Use
```
bulk get
```
to get all tickers in one request
Do not retry immediately after receiving 429 — Wait for a while (tens of seconds to minutes) before retrying
Filter with query parameters — Reduce unnecessary fields and date ranges, get all required data in one request

Subscription Plans & API Availability

Accessibility and obtainable data period of each API vary by plan. Check plan restrictions before proposing commands. If the plan is unknown, present the command and clearly state the required plan.

Quick reference of minimum required plan

Minimum required plan	CLI command
Free	`eq master` , `eq daily` , `eq earnings-calendar` , `fins summary` , `mkt calendar`
Light	`eq investor-types` , `idx daily-topix`
Standard	`mkt margin-interest` , `mkt short-ratio` , `mkt short-sale-report` , `mkt margin-alert` , `idx daily` , `deriv options-225`
Premium	`eq am` , `fins details` , `fins dividend` , `mkt breakdown` , `deriv futures` , `deriv options`
Add-on	`eq minute` , `eq trades` (requires separate minute bar/tick data add-on subscription)

Plan hierarchy: Free < Light < Standard < Premium (higher plans include all APIs of lower plans)

Free plan restrictions: CSV/bulk download is not supported (except
mkt calendar
). Only API access is allowed. Data is limited to the window "12 weeks ago to 2 years and 12 weeks ago" (latest 12 weeks and historical data older than 2 years cannot be obtained).

Refer to references/plans.md for detailed obtainable periods and data ranges.

Data Freshness (Update Timing)

J-Quants API data is updated sequentially after market events. The freshness of obtainable data changes depending on the relationship between current time and update time.

Update summary by time zone (JST)

Estimated update time	Reflected data
~12:00	Morning session OHLCV ( `eq am` ) updated for the current day
~16:30	Stock price OHLCV, minute bars, tick data, indices, short selling ratios, daily margin balances updated for the current day
~17:30	Ticker master, short selling balance report updated
~18:00	Trading breakdown, investor sector data (weekly), financial information (flash) updated
~19:00	Earnings announcement scheduled date updated (irregular, linked to JPX)
~24:30	Financial information (final), financial statements (final) updated
~27:00	Derivatives (futures, options) updated for the current day (27:00 = 3:00 AM next day)

Guidelines for agent judgment

When asked for current day data before the update time: Inform the user that "The current day's data will be reflected around XX:XX. At present, the latest data is from the previous business day."
Weekly data (weekend margin balance, investor sector data): Margin balance is updated around 16:30 on Tuesday, investor sector data around 18:00 on Thursday. For other days of the week, the latest data is from the previous week.
Derivatives are updated at 27:00 (3:00 AM next day): The previous day's data will not be available until early morning of the next business day.
When the user says "data is outdated": Check update time, weekly cycle, holidays, plan period restrictions in order.

Refer to references/data-update-schedule.md for detailed judgment flow and scenario examples.

Common Pitfalls

Mistake	Correct writing	Reason
`eq daily --code X --output csv`	`--output csv eq daily --code X`	clap parses flags after the subcommand as options of the subcommand itself
`--save out.csv eq daily` (output not specified)	`--output csv --save out.csv eq daily`	Table format does not support `--save` . Explicitly specify csv/json/parquet for saving
`mkt short-ratio --code 0050`	`mkt short-ratio --s33 0050`	short-ratio API is designed to filter by 33 industry classification, not by ticker
`mkt short-sale-report --date 2024-08-01`	Use `--disc-date` or `--calc-date`	Announcement date and calculation date are separate concepts. `--date` flag does not exist
`eq daily --date 2026-03` (month only)	`--date` uses YYYY-MM-DD format	Month specification is only supported for bulk APIs. Individual APIs use daily units
Repeatedly run `eq daily --code X` in a loop for all tickers	`bulk get --endpoint /equities/bars/daily --date YYYY-MM --download`	Avoid API rate limit & improve efficiency. All tickers can be obtained in one file
`--output parquet eq daily` ( `--save` not specified)	`--output parquet --save out.parquet eq daily`	Parquet does not support streaming output, so file saving is required
`-f date,code` (lowercase field names)	`-f Date,Code` (check with `jquants schema <endpoint>` )	API field names are PascalCase and case-sensitive
FS becomes `"N items"` when displaying `fins details` in table view	Use `--output json fins details`	FS field is a nested JSON object, which is summarized in table view
Retry immediately after receiving 429	Wait for tens of seconds to minutes before retrying	Continuous excessive exceeding will result in about 5 minutes of blocking. Immediate retry prolongs the blocking period
Use `bulk get` or `--output csv` with Free plan	Use individual APIs ( `eq daily --code X` ), or prompt to upgrade to a higher plan	Free plan does not support CSV/bulk download (except `mkt calendar` ). Only API access is available
Use `idx daily` or `deriv options-225` with Light plan	Inform the user that Standard plan is required	These APIs require Standard or higher plan. Refer to references/plans.md for plan and command correspondence
Assume that the "today's stock price" obtained with `eq daily` at 16:00 is the latest	Inform the user that "The current day's data will be reflected around 16:30. At present, the latest data is from the previous business day."	Stock price OHLCV is updated for the current day around 16:30. Before update, the latest data is from the previous business day
Assume that the `mkt margin-interest` obtained on Monday morning is from last week	Inform the user that it is data as of Friday of the week before last. The data for last Friday will be reflected after 16:30 on Tuesday	Weekend margin balance is weekly data updated around 16:30 on the 2nd business day (usually Tuesday)

jquants-cli-usage

NPX Install

Tags

SKILL.md Content (Chinese)