What this skill does
korail2 on top of scripts/ktx_booking.py layer the helper to handle KTX/Korail search, reservation, reservation confirmation, and cancellation.
Due to the recent Dynapath anti-bot check in the Korail app, the original korail2 0.4.0 example alone may MACRO ERROR may fail. This skill assumes the helper x-dynapath-m-token, Sid, attaches the latest app version(250601002) to restore the actual booking flow.
When to use
- "Find me a KTX from Seoul to Busan"
- "Check my Korail reservation"
- "Cancel my KTX"
- "Book the fastest KTX after 9 AM"
- "Find discounted trains with the N Card"
- "Show me my N Card list"
- "Book with the N Card discount applied"
When not to use
- In the case of SRT booking
- When actual payment confirmation must be automated
- When trying to put credentials in plaintext
Prerequisites
- Python 3.10+
python3 -m pip install korail2-ncard pycryptodome
Required environment variables
KSKILL_KTX_IDKSKILL_KTX_PASSWORD
Credential resolution order
- If it is already in an environment variable use it as is.
- If the agent is using its own secret vault (1Password CLI, Bitwarden CLI, macOS Keychain, etc.) you may retrieve it from there and inject it as an environment variable.
~/.config/k-skill/secrets.env(default fallback) — plain dotenv file, permissions0600.- If there is nothing ask the user and save it to 2 or 3.
Saving to the default path is only a fallback, not mandatory.
Inputs
- Departure station
- Arrival station
- Date:
YYYYMMDD - Desired start time:
HHMMSS - Number of people and passenger type
- Seat preference
- Copied from the search results
train_id
Workflow
0. Install the package globally when missing
python3 -c 'import korail2, Crypto' If it fails, do not work around it with another implementation; first try installing the global Python package.
python3 -m pip install korail2-ncard pycryptodome
1. Ensure credentials are available
KSKILL_KTX_ID, KSKILL_KTX_PASSWORD Check whether the environment variable is set. If not, obtain it according to the credential resolution order above.
Do not directly scrape the website or look for other unofficial routes just because there is no secret.
2. Search first via the helper
Always search through the helper.
python3 scripts/ktx_booking.py search 서울 부산 20260328 090000 --limit 5
The default --train-type 은 ktx is. To book non-KTX routes such as ITX-Cheongchun (e.g., Namchuncheon↔Yongsan), ITX-Saemaeul, and Mugunghwa-ho, specify --train-type with.
python3 scripts/ktx_booking.py search 남춘천 용산 20260503 150000 --train-type itx-cheongchun
Options: ktx, itx-saemaeul, mugunghwa, nuriro, tonggeun, itx-cheongchun, airport, all.
At the reservation step (reserve) also pass the same --train-type value as is so that stable train_id matching is not broken.
To include trains with no seats in the candidates, --include-no-seats, and if you also want to see trains available for waitlist reservation, --include-waiting-list add.
3. Present the shortlist
Always check the following before booking.
indextrain_id- Departure/arrival time
- Train type (
train_type) - General room/Special room availability
- Waitlist reservation availability
4. Reserve only after the target train is unambiguous
From the search results, train_id book only after selecting. This value is a stable selector created by the helper by combining the train number/operating date/time/station code, so on re-search, if the same train still exists it will be selected as is, and if not, it will fail.
python3 scripts/ktx_booking.py reserve 서울 부산 20260328 090000 --train-id <train_id> --seat-option general-first
If you selected a non-KTX route such as ITX at the search step, also pass the same to reserve --train-type passes.
python3 scripts/ktx_booking.py reserve 남춘천 용산 20260503 150000 --train-id <train_id> --train-type itx-cheongchun --seat-option general-first
The response includes the reservation number, fare, and purchase deadline. Payment is not automated.
When there are no seats, at the search step --include-waiting-list turn on and at the reservation step --try-waiting you can try up to waitlist reservation with.
4-1. N-card discounted reservation
To apply the N-card discount, first look up the list of N-cards you hold and check the card number.
python3 scripts/ktx_booking.py ncard-list
Search for discount trains with the N-card (--ncard-index 는 ncard-list sequence number in the results). ncard-list masks and outputs the card number to reduce log/shell exposure.
python3 scripts/ktx_booking.py ncard-search 대전 서울 20260512 100000 --ncard-index 1 --train-type ktx
From the response, train_id copy and reserve to the same --ncard-index attach and reserve.
python3 scripts/ktx_booking.py reserve 대전 서울 20260512 100000 \
--train-id <train_id> \
--ncard-index 1
--ncard-index If you specify --adults passenger options such as are ignored and it is processed as 1 N-card passenger. --ncard-no Direct input is also supported, but it is not recommended because it may remain in the shell history. Payment is not automated.
The N-card feature requires the korail2-ncard package. If it is missing, installation guidance is output when the corresponding command is run.
5. Inspect or cancel
Cancellation proceeds only after re-querying and identifying the target reservation.
python3 scripts/ktx_booking.py reservations
python3 scripts/ktx_booking.py cancel <reservation_id>
Done when
- If it is a search, train candidates are organized
- If it is a reservation, the reservation result and time limit are confirmed
- If it is a cancellation, which reservation was canceled remains
Failure modes
- Login failed
- Sold out
- Korail anti-bot rule change
Notes
scripts/ktx_booking.py는 upstreamkorail2helper that compensates for anti-bot regressionskorail2is a KTX/Korail-only surface, so the train type and passenger model are clear- It is not automated through payment completion
- Avoid aggressive polling