{"openapi":"3.1.0","info":{"title":"KDP Intelligence API","description":"Niche demand + competition intelligence for Kindle Direct Publishing authors.\n\n## Payment\nPaid endpoints require an `X-Payment` header containing a base64-encoded [x402](https://github.com/coinbase/x402) USDC authorization on Base (0.03 USDC per query). Missing or invalid payment returns HTTP 402 with machine-readable payment instructions.\n\nThis API uses x402 v2 with Bazaar discovery — compatible agents can discover and pay for this service automatically.\n\n## Agent Usage\n1. Call `GET /v1/niches` (free) to discover available keywords.\n2. For each keyword of interest, call `GET /v1/niche/{keyword}` with a valid `X-Payment` header to retrieve full intelligence data.\n3. On HTTP 402, parse the response body `accepts[0]` fields to construct payment.\n\n## Docs\n- Integration guide: `/docs/integration-guide`\n- OpenAPI spec: `/openapi.json`\n- Interactive docs: `/docs` (Swagger UI)","version":"0.1.0","x-payment-required":{"description":"This API uses the x402 payment protocol. Paid endpoints return HTTP 402 with machine-readable payment instructions when the X-Payment header is absent or invalid.","production":{"version":1,"accepts":[{"scheme":"exact","network":"base-mainnet","maxAmountRequired":"30000","payTo":"0xcafe605dFeBa96ba84C2d520e3cF972CaC184E3a","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","extra":{"name":"USD Coin","version":"2"}}]},"staging":{"version":1,"accepts":[{"scheme":"exact","network":"base-sepolia","maxAmountRequired":"30000","payTo":"0xcafe605dFeBa96ba84C2d520e3cF972CaC184E3a","asset":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","extra":{"name":"USD Coin","version":"2"}}]},"costPerQueryUSDC":0.03,"paymentHeader":"X-Payment","paymentScheme":"x402","docs":"https://github.com/coinbase/x402"}},"paths":{"/v1/niche/{keyword}":{"get":{"tags":["niches"],"summary":"Get KDP niche intelligence","description":"Return demand, competition, BSR, revenue, and pricing intelligence for a KDP niche keyword.\n\nRequires X-Payment header: x402 USDC authorization (0.03 USDC on Base).\nPayment is verified and settled via CDP Facilitator, which auto-lists this\nservice on Agentic.Market after the first successful settlement.\n\nPerforms exact match first, then falls back to fuzzy (ILIKE) search.","operationId":"get_niche_v1_niche__keyword__get","parameters":[{"name":"keyword","in":"path","required":true,"schema":{"type":"string","title":"Keyword"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NicheResponse"}}}},"402":{"description":"Payment required — include X-Payment header with x402 USDC authorization","content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer","example":1},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"base-mainnet"},"maxAmountRequired":{"type":"string","example":"30000"},"payTo":{"type":"string"},"asset":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}}},"error":{"type":"string"}}},"example":{"x402Version":1,"accepts":[{"scheme":"exact","network":"base-mainnet","maxAmountRequired":"30000","payTo":"0xcafe605dFeBa96ba84C2d520e3cF972CaC184E3a","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}],"error":"Payment required — include X-Payment header with EIP-3009 authorization"}}}},"404":{"description":"Niche not found — includes list of available keywords"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-payment-required":true,"x-payment-amount-usdc":0.03,"x-payment-network":"base-mainnet","x-payment-asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","x-payment-scheme":"exact"}},"/v1/niches":{"get":{"tags":["niches"],"summary":"List all available KDP niches","description":"Discover all available KDP niche keywords, ordered by demand score descending.","operationId":"list_niches_v1_niches_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Results per page","default":20,"title":"Limit"},"description":"Results per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"Offset"},"description":"Pagination offset"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NichesListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/health":{"get":{"tags":["meta"],"summary":"Health","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"NicheResponse":{"properties":{"keyword":{"type":"string","title":"Keyword","description":"Normalized niche keyword"},"demand_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Demand Score","description":"Keyword demand score (0–100)"},"competition_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Competition Score","description":"Competition intensity (0–100)"},"bsr_range":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bsr Range","description":"Amazon BSR range, e.g. '1,000–5,000'"},"monthly_revenue_estimate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monthly Revenue Estimate","description":"Estimated monthly revenue (USD)"},"review_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Review Threshold","description":"Min review count to rank competitively"},"pricing":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pricing","description":"Average book price (USD)"},"data_freshness":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Freshness","description":"ISO 8601 timestamp of last data refresh"},"query_cost_usdc":{"type":"number","title":"Query Cost Usdc","description":"Per-query cost in USDC","default":0.03},"api_version":{"type":"string","title":"Api Version","description":"API version","default":"0.1.0"}},"type":"object","required":["keyword","demand_score","competition_score"],"title":"NicheResponse"},"NichesListResponse":{"properties":{"niches":{"items":{"$ref":"#/components/schemas/NicheResponse"},"type":"array","title":"Niches"},"total":{"type":"integer","title":"Total"},"api_version":{"type":"string","title":"Api Version","default":"0.1.0"}},"type":"object","required":["niches","total"],"title":"NichesListResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}