# ChyaKharcha

> ChyaKharcha (chyakharcha.com) is a Nepali creator marketplace: creators sell physical, digital and print-on-demand products and receive "chiya" support. ChyaKharcha handles payments (eSewa for Nepal, Stripe cards internationally), delivery (Pathao in Nepal, ChyaKharcha international shipping), and payouts. Developers and AI agents can manage a shop and sell products through a REST API, an MCP server, and a drop-in widget — all with one API key.

All amounts are Nepali rupees (NPR). A 10% platform fee applies to product subtotals; delivery fees pass through.

## Get a key
- Create keys at https://www.chyakharcha.com/developer/dashboard (sign in first).
- `ck_live_sk_…` secret key: manage your shop (products, stock, discounts), read orders, open checkouts. Keep it server-side or in your AI client's settings.
- `ck_live_pk_…` publishable key: safe in web pages; reads public listings and opens checkouts (used by the widget).
- `ck_test_…` keys: checkouts are simulated, no money moves; they can't change your live shop.
- Send it as `Authorization: Bearer <key>`.

## For AI assistants
- MCP server (Claude Desktop, claude.ai connectors, Claude Code, any MCP client): `https://www.chyakharcha.com/api/mcp` with header `Authorization: Bearer ck_live_sk_…`. Tools: get_account, list_products, get_product, create_product, update_product, archive_product, quote_delivery, create_checkout_link, list_orders, get_order, update_order_status.
- OpenAPI 3.1 spec (ChatGPT custom GPT Actions → "Import from URL", Postman, codegen): https://www.chyakharcha.com/api/v1/openapi.json — auth type "API key", "Bearer".
- Claude Code: `claude mcp add --transport http chyakharcha https://www.chyakharcha.com/api/mcp --header "Authorization: Bearer ck_live_sk_…"`
- Always call get_account (GET /api/v1/me) first to confirm which shop you are changing.

## Rules an agent must respect
- A product's listed `price_npr` is fixed once created (fair-pricing policy). Change what buyers pay with `discount_percent` (0–90).
- Physical products need `weight_grams` (1–10000) and the seller must have a delivery setup (store address or a "delivery by you" city) on the shop page.
- Product names are unique within a shop; `sku` is optional and unique within a shop.
- `stock_quantity` null means stock isn't tracked; a number counts down automatically as orders are paid; 0 shows "Sold out".
- Archiving (DELETE) only hides a product; order history is kept.
- Image URLs must be https; they are copied into ChyaKharcha storage.

## REST API — base https://www.chyakharcha.com/api/v1
- GET /me — the account this key acts as.
- GET /products?seller=&type=physical|digital|pod&limit=&offset= — listings. With a secret key and no seller: your whole shop incl. inactive, stock, SKU.
- POST /products — create {name, price_npr, type, description, weight_grams, stock_quantity, sku, images[], discount_percent, active}.
- GET /products/{id} · PATCH /products/{id} (only fields sent change) · DELETE /products/{id} (archive).
- POST /delivery/quote — {product_id, quantity, destination:{country:"NP"|ISO-2, city, zone_id?, state?, postal_code?}} → delivery options with fee_npr.
- POST /checkout/sessions — {product_id, quantity, success_url, cancel_url?, customer_email?, metadata?} → {id, url}. Redirect the buyer to url; they return to success_url?checkout_session_id=…&order_id=…. Selling another shop's product credits your referral share automatically.
- GET /checkout/sessions/{id}
- GET /orders?role=seller|partner&status=pending|completed|cancelled · GET /orders/{id} · PATCH /orders/{id} {status:"completed"|"cancelled", note}
- GET/POST /webhook_endpoints · DELETE /webhook_endpoints/{id}
- Errors: {"error":{"type":"invalid_request|authentication_required|permission_denied|not_found|conflict|rate_limited|api_error","message":"…","param":"…"}}

## Webhooks
Events: order.paid, order.updated, checkout.completed, product.updated. POST JSON `{id, type, livemode, created, data}` with header `CK-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>`. Verify with your endpoint's `whsec_…` secret and reject timestamps older than 5 minutes. Return any 2xx. Failed deliveries are retried and can be resent from the dashboard.

## Widget (no backend needed)
```html
<div data-ck-shop="smudgewears" data-ck-key="ck_live_pk_…" data-ck-type="physical"></div>
<button data-ck-buy="793" data-ck-key="ck_live_pk_…">Buy now</button>
<script src="https://www.chyakharcha.com/ck.js" async></script>
```

## Docs
- Developer docs: https://www.chyakharcha.com/developer/docs
- Embeds (iframes for profile, support button, services): https://www.chyakharcha.com/developer