# jp-finance

> Which JPY rate did Japan Customs publish for this currency and date? Is this business on a Japan FSA register or warning list? Hosted MCP and HTTP: no install, works from cloud agents. Rates as published with base units and period; exact-match register lookups with names as listed; source URLs, retrieval times and SHA-256 hashes on every answer. Single lookups free; 1-50 item rate batch $0.01 via x402 (USDC). Facts with sources only: not a market or remittance rate, no tax calculation, no advice.

Data sources: Japan Customs weekly exchange rates for customs valuation (index.htm and weekly CSV files, PDL1.0); Financial Services Agency of Japan registers and warning lists (xlsx). Relayed and restructured by MK Career Planning; not an official service of either agency.
Customs rates are reference data for customs declarations and bookkeeping. They are not market, bank or remittance rates. This service calculates no tax and does not choose a date or rate for you.
FSA results are exact-match facts with the as-of date of each list. Not being listed does not mean safe; being listed is not a recommendation. No investment advice; no rating of businesses or crypto-assets.

## Connect

- Paid HTTP (x402 v2): POST https://jp-finance-production.mk-career-planning.workers.dev/v1/customs-fx/batch (jp_customs_fx_batch)
- MCP (streamable HTTP): https://jp-finance-production.mk-career-planning.workers.dev/mcp
- OpenAPI: https://jp-finance-production.mk-career-planning.workers.dev/openapi.json
- x402 discovery: https://jp-finance-production.mk-career-planning.workers.dev/.well-known/x402

## Free tools

- catalog: List the tools of this server with prices, data sources, licensing, daily limits and data freshness.
- jp_customs_fx: Which JPY rate did Japan Customs publish for this currency on this date? Input: ISO 4217 code and YYYY-MM-DD date. Returns status (valid/invalid/unknown), the inclusive effective period, the JPY rate as published with its base units (1 or 100), source URLs, retrieval and verification times and SHA-256 hashes. Dates from 2021-08-15. Unpublished periods and unlisted currencies return unknown. Reference for customs and bookkeeping only; not a market or remittance rate; no tax calculation.
- jp_fsa_registry_lookup: Is this business (name, registration or 13-digit corporate number) on a Japan FSA register or warning list? Exact match (optional domain) against: registered financial instruments, crypto-asset exchange, electronic payment instruments, funds transfer and money lending businesses, and FSA warnings to unregistered businesses. Returns matches, unconfirmed name candidates, domain links only when a list states them, and which lists were checked as of when. Absence does not mean safe; no advice.
- get_receipt: Re-fetch the stored result of a settled paid call by its receipt_id, for when the response was lost after payment. Free. Unknown or unsettled receipt ids return RECEIPT_NOT_FOUND. Results are kept for 90 days after settlement.
- HTTP: GET https://jp-finance-production.mk-career-planning.workers.dev/v1/customs-fx, GET https://jp-finance-production.mk-career-planning.workers.dev/v1/fsa/lookup return the same data as the MCP tools. GET https://jp-finance-production.mk-career-planning.workers.dev/v1/receipts/<receipt_id> is get_receipt.

## Paid tools (x402, USDC)

- jp_customs_fx_batch ($0.01 per call, eip155:8453): Which JPY rates did Japan Customs publish for these 1-50 currency/date pairs? One call returns ordered per-item status, effective periods, JPY rates as published with base units (1 or 100), source URLs, retrieval and verification times and hashes, read from one dataset snapshot. Dates from 2021-08-15. Unpublished periods and unlisted currencies return unknown. Not charged if no item can be answered. No date selection, tax calculation, market or remittance rates, or forecasts.

### Pay over HTTP (x402 v2)

1. POST the JSON body without payment. The answer is HTTP 402 with a PAYMENT-REQUIRED header: base64 JSON of the x402 v2 PaymentRequired (scheme exact, USDC, amount 10000 = $0.01). The body repeats it.
2. Sign the payment with an x402 v2 client and POST the same body again with the PAYMENT-SIGNATURE header (base64 PaymentPayload).
3. On success: HTTP 200, the result JSON with receipt_id, and a PAYMENT-RESPONSE header (base64 SettlementResponse with the transaction hash). If verification or settlement fails you get 402 again, no result, and no charge.
4. Retrying with the same PAYMENT-SIGNATURE returns the stored result and the same receipt_id without charging again.

```sh
curl -i -X POST https://jp-finance-production.mk-career-planning.workers.dev/v1/customs-fx/batch -H 'Content-Type: application/json' -d '{"items":[{"currency":"USD","date":"2026-10-07"}]}'
```

```ts
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
const client = new x402Client();
registerExactEvmScheme(client, { signer }); // signer: an EVM account holding USDC
const pay = wrapFetchWithPayment(fetch, client);
const res = await pay("https://jp-finance-production.mk-career-planning.workers.dev/v1/customs-fx/batch", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ items: [{ currency: "USD", date: "2026-10-07" }] }) });
```

### Pay over MCP

Call the tool without payment to receive the x402 requirement in the result _meta 'x402/error', then retry with the signed payment in _meta 'x402/payment'.

Both ways share one ledger, one receipt store and one daily limit.
Daily limits apply (Japan time); when reached the tool returns DAILY_CAP_REACHED (HTTP 429) and does not charge.

## Rate limits

- Free calls (free HTTP endpoints under /v1/ and free MCP tools) are limited to 300 requests per 60 seconds per client (a client is keyed by a one-way hash of its IP address and the first 64 characters of its User-Agent; neither is stored. The User-Agent can be set by anyone, so this split is for fairness between clients behind a shared gateway, not a security control). Over the limit, HTTP returns 429 RATE_LIMITED with a Retry-After header and MCP tools return the error RATE_LIMITED. Paid calls are not rate limited.

## Provenance and fetch_status

Responses carry provenance[] (source, upstream_updated_at, retrieved_at, content_sha256, parser_version, fetch_status). fetch_status values:

- found: The upstream document was retrieved and contains the data used for this answer.
- empty: The upstream was retrieved, but it has no item for this query (for example JMA had no bulletin for that area in its feeds, or the municipality is not in the list). The state is unknown: empty does NOT mean 'none in effect'.
- stale: The data was retrieved but is older than the freshness threshold for its kind; treat it with care.
- unavailable: The upstream could not be retrieved, read or used (network error, withdrawn bulletin, paused source, or data not yet loaded).
- unsupported: The query is outside what this source covers (for example a date JMA does not issue warnings for yet, or a period before the source's records).

## Errors

- PAYMENT_REQUIRED (x402; pay and retry)
- INVALID_INPUT (malformed body or not 1 to 50 items; not charged)
- NO_BILLABLE_RESULT (every item invalid, out of range or source unavailable; not charged)
- PAYMENT_ALREADY_USED (payment settled for different arguments; not charged again)
- PAYMENT_IN_PROGRESS (retry shortly with the same payment)
- DAILY_CAP_REACHED (daily limit in Japan time; not charged)
- PAUSED (operator pause; not charged)
- LEDGER_UNAVAILABLE (refused; not charged)
- NO_BILLABLE_RESULT (422; every item invalid, out of range or source unavailable; not charged)
- RECEIPT_NOT_FOUND (get_receipt)
- RATE_LIMITED (free calls over the per-client limit; HTTP 429 with Retry-After; not charged)

## Terms

- unknown means the rate could not be confirmed from the checked sources (for example the period is not yet published, the currency is not listed, or the source could not be verified recently). It is not a statement that no rate exists.
- valid means only that the published rate for the supplied date was found; it does not mean a declaration or an accounting treatment is correct.
- For FSA lookups, read sources_checked and coverage_complete before relying on an answer.

## Privacy and support

- Operator: MK Career Planning
- Terms of Service: https://jp-finance-production.mk-career-planning.workers.dev/terms
- Privacy policy: https://jp-finance-production.mk-career-planning.workers.dev/privacy
- Support (free): https://jp-finance-production.mk-career-planning.workers.dev/support (mk.career.planning@gmail.com)