Programmatic Japanese FX gotobi (五十日) date calendar with holiday adjustments through 2099.
What it does
The Gotobi Calendar API is the only known programmatic source for Japanese FX gotobi (五十日) dates — the 5th, 10th, 15th, 20th, 25th, and end-of-month settlement dates that drive USD/JPY demand patterns. The API provides holiday-adjusted gotobi dates through 2099, shifting dates to the preceding business day when they fall on Japanese public holidays or weekends. This makes it directly useful for algorithmic FX trading strategies that exploit the well-documented gotobi effect on yen pairs.
The `/gotobi/dates` endpoint accepts an optional `month` query parameter in YYYY-MM format and returns the adjusted gotobi dates for that month. Additional endpoints include `/gotobi/today` (check if today is a gotobi date), `/gotobi/next` (find the next upcoming gotobi date with days-until count), and a parallel set of Japanese public holiday endpoints (`/gotobi/holidays`, `/gotobi/holidays/today`, `/gotobi/holidays/next`). All responses are JSON with clear schemas.
The endpoint is x402-enabled and costs $0.01 USDC per call on Base. Alternative access methods include an MCP gateway, API key with free $0.05 credit, or the `x402-pay` Python SDK. The API is live and returns a well-formed 402 challenge with a sample response embedded.
Capabilities
Use cases
- —Building algorithmic FX trading strategies around the gotobi effect on USD/JPY
- —Scheduling trade execution around Japanese settlement dates
- —Checking whether today is a gotobi date to trigger automated workflows
- —Looking up Japanese public holidays for trading calendar construction
- —Pre-computing monthly gotobi schedules for backtesting
Fit
Best for
- —FX algorithmic traders targeting the gotobi effect
- —Quant researchers studying USD/JPY seasonal patterns
- —Trading systems that need a reliable Japanese settlement calendar
- —AI agents automating FX trade scheduling
Not for
- —General-purpose global holiday lookups (Japan-only)
- —Non-financial calendar applications
- —Real-time FX price data or execution
Quick start
pip install x402-pay
import x402_pay
r = x402_pay.get('https://gotobi.hugen.tokyo/gotobi/dates?month=2026-03')
print(r.json())Example
Response
{
"year": 2026,
"count": 6,
"month": 3,
"description": "Gotobi dates for 2026-03",
"gotobi_dates": [
"2026-03-05",
"2026-03-10",
"2026-03-13"
]
}Endpoint
Quality
Full OpenAPI 3.1 schema with typed response models, live 402 challenge with embedded sample data, clear endpoint documentation. Docked slightly because no dedicated docs page beyond Swagger, the sample response count field (6) doesn't match the 3 listed dates (likely truncated in the challenge), and no pricing page exists.
Warnings
- —Sample response in 402 challenge shows count=6 but only 3 dates listed — may be truncated in the challenge payload
- —No dedicated pricing or README page; pricing inferred solely from 402 challenge notice ($0.01 USDC on Base)
- —Root URL returns 404; documentation only available at /docs (Swagger UI)
Citations
- —The API describes itself as the only programmatic source for Japanese FX gotobi dates with holiday shifts through 2099https://gotobi.hugen.tokyo/docs
- —The /gotobi/dates endpoint accepts an optional month parameter in YYYY-MM formathttps://gotobi.hugen.tokyo/docs
- —Payment is $0.01 USDC on Base per callhttps://gotobi.hugen.tokyo/gotobi/dates
- —Alternative access via MCP gateway, API key, or x402-pay Python SDKhttps://gotobi.hugen.tokyo/gotobi/dates