# Micro Data API Factory — Broker

> Wallet-free API-key issuance + free-trial credit + metered broker call
> for JP Local Pack, JP Data Enrich, and JP Grants. No signup, no wallet.
> POST /keys/create → get a key, get trial credit, start calling.

## Quick start

1. curl -X POST https://api.kasanegi.com/keys/create
   → returns { api_key, entitlements, balance_micro_usdc, ... } ONCE.
2. curl -H "X-API-Key: <key>" "https://api.kasanegi.com/products"
   → list the current three product suites and their broker_product_id values.
3. curl -X POST -H "X-API-Key: <key>" -H "Content-Type: application/json" \
        --data '{"product_id":"jp-local-pack-v1-combined-payroll-summary","query":{"monthly_salary":300000,"year_month":"2026-05"}}' \
        https://api.kasanegi.com/broker/call
   → JP Local Pack JSON, balance decremented.
4. Optional feedback: POST https://api.kasanegi.com/feedback with product_id, feedback_type, rating, and message. Do not include secrets, contact details, or personal data.

## Model

- **product suite**: one of jp-local-pack, jp-data-enrich, jp-grants.
- **broker_product_id**: the metered endpoint id passed to /broker/call.
- **endpoint**: path under a product suite.
- **api_key**: wallet-free bearer; hashed in storage.
- **credit_ledger**: + grants (trial) / − consumptions (broker calls).
- **entitlements**: which products a key can call, with policy.
- **trial_policies**: active trials; each new key auto-receives them.

## Factory principle

New products should be added to the internal catalog only after their product
page, discovery surfaces, preview tests, broker trial, and telemetry gates pass.
Public discovery stays limited to the current sales catalog.

## Pricing

- Default free trial: $0.005 per active policy (covers 5 calls on the
  $0.001 class).
- After trial expires there are multiple production sales paths. x402 is one
  option, not the only one.
- Broker never charges above the registry endpoint price; it only meters.

## Buyer paths (= production sales channels)

This origin supports more than one paid sales path. Pick the one that
fits the buyer:

1. **Wallet-free preview** — `https://api.kasanegi.com/preview/v1/{local|enrich|grants}/...`
   Same JSON shape as the paid path. No signup, no wallet, no crypto. For
   evaluation only.
2. **Marketplace / API-key path** — `https://api.kasanegi.com/marketplace/rapidapi/v1/{local|enrich|grants}/...`
   Origin route behind a marketplace proxy (RapidAPI-class). End buyers pay
   the marketplace by card or platform credit; the marketplace proxies the
   request here over HTTPS with the shared secret header
   `X-Kasanegi-Marketplace-Secret`. End buyers should not call this origin
   path directly. Status: One public marketplace listing is live for all current products at https://rapidapi.com/kasanegi123/api/jp-local-pack-japan-payroll-invoice-tax-apis.
   Public marketplace listing URL: https://rapidapi.com/kasanegi123/api/jp-local-pack-japan-payroll-invoice-tax-apis
3. **x402 direct micropayment** — `https://api.kasanegi.com/v1/{local|enrich|grants}/...`
   402 envelope without X-PAYMENT; settle and retry with X-PAYMENT (open
   x402 protocol). USDC on Base mainnet via CDP facilitator. Optional, for
   agent-native buyers.
4. **Card / fiat checkout (Stripe / Polar / equivalent)** — not yet wired.
   Owner must create the merchant account and configure pricing.

The full sales-channel manifest with per-channel status is at
`https://api.kasanegi.com/products` under `sales_channels`, and at
`https://api.kasanegi.com/.well-known/broker-manifest.json` under `sales_channels`.

## Attribution & source

Each product carries its own upstream attribution (see product detail).

## Discovery

- /.well-known/broker-manifest.json — machine-readable product list (= includes sales_channels)
- /.well-known/x402 — origin-level x402 auto-discovery (= every public-sold endpoint with network/asset/payTo/amount). x402 is one option, not the only one.
- /supported — x402scan-compatible alias of /.well-known/x402
- /products — JSON product catalog (= includes sales_channels)
- /product-status.json — machine-readable release and current product status (= includes sales_channels)
- /portal — human-readable buyer portal
- /portal.md — Markdown buyer portal for LLM readers
- /feedback/schema — accepted feedback fields and privacy boundary
- /openapi.json — OpenAPI 3.1.0 (= includes marketplace_rapidapi paths and x-sales-channels)
- MCP gateway — https://mcp.kasanegi.com/mcp (POST JSON-RPC 2.0; GET returns human/LLM-readable connection guidance)
- /marketplace/rapidapi/v1/{local|enrich|grants}/... — marketplace API-key origin path (= for marketplace proxy use, not direct buyer use)