# Soroban Data Works
Japan micro-data API for AI agents and developers. Small, precise,
rule-based answers about Japanese business calendars and consumption tax.
No API keys, no accounts: paid endpoints are bought per call with x402
(USDC on Base, network eip155:8453). Service status: GET /health
("mode" is "live" when payments are configured, "demo" otherwise).

Free:
- GET /v1/jp/holidays?year=2026  (national holidays for 2000-2100, computed from the official rules)

Paid (x402, USDC on Base):
- GET /v1/jp/is-business-day?date=2026-11-04  ($0.002)
- GET /v1/jp/business-days?start=2026-11-01&end=2026-11-30  ($0.003)
- GET /v1/jp/consumption-tax?amount=10000&rate=10  ($0.002; rate is 10 or 8)

How to buy a paid endpoint:
1. GET the endpoint without payment. You receive HTTP 402 with a
   PAYMENT-REQUIRED header (base64 JSON) and the same JSON in the body:
   accepts[0] states scheme, network, amount (atomic USDC units),
   asset and payTo.
2. Sign an EIP-3009 transferWithAuthorization for exactly those terms.
3. Retry the same GET with the signed payload base64-encoded in a
   PAYMENT-SIGNATURE header.
4. The server verifies and settles through a facilitator, then returns
   200 with the data. Invalid, malformed or unverifiable payments are
   rejected with 402 and never unlock data. Parameters are validated
   BEFORE payment, so an invalid request returns 400 and is never charged.

Example responses:
- is-business-day: {"date": "2026-11-04", "weekday": "Wed", "is_business_day": true, "holiday_name": null}
- holidays: {"year": 2026, "count": 18, "holidays": [{"date": "2026-01-01", "name": "元日", "weekday": "Thu"}]}
- consumption-tax: tax rounded once per tax rate under Japan's qualified
  invoice system; floor/round/ceil variants are all returned.

Machine-readable docs: /openapi.json (OpenAPI 3.1, includes response
schemas, the 402 response shape and examples).