SuperAPI AI Directory

ktx-booking

Coding & development

View repository

Updated 10-15 21:02

About this skill

KTX Booking

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_ID
  • KSKILL_KTX_PASSWORD

Credential resolution order

  1. If it is already in an environment variable use it as is.
  2. 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.
  3. ~/.config/k-skill/secrets.env (default fallback) — plain dotenv file, permissions 0600.
  4. 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.

  • index
  • train_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 는 upstream korail2 helper that compensates for anti-bot regressions
  • korail2 is a KTX/Korail-only surface, so the train type and passenger model are clear
  • It is not automated through payment completion
  • Avoid aggressive polling