handcart

One cart for India's quick-commerce apps. Search across Blinkit and Zepto at once, compare prices for the same product, then cart, checkout and pay with UPI on whichever is cheaper — as a CLI, a TypeScript library, and an MCP server for Claude, Cursor and other agents.

$ handcart search "surf excel"
surf excel · 2 platforms

Surf Excel Matic Top Load Liquid Detergent · 5 kg
  * zepto   ₹601   MRP ₹810  -26%   in stock  a3e1b947-86b8-4311-ab00-8b47928c8b0a
    blinkit ₹629   MRP ₹810  -22%   in stock  763523
  handcart zepto cart add a3e1b947-86b8-4311-ab00-8b47928c8b0a

Payment is headless on both platforms. The UPI QR is handed to whoever pays either as a qrbaton pay page (items, bill, delivery address, one-tap GPay / PhonePe / Paytm) or as a plain QR image.

Requirements

• Node.js ≥ 22

• A Chromium-based browser, auto-detected. Zepto needs it to mint its WAF token at login; Blinkit only needs it for pay --browser.

Related MCP server: blinkit-mcp

Install

npm install -g handcart
handcart setup            # guided: browser, logins, delivery addresses, then doctor

Or run it without installing: npx handcart search milk.

As a library: npm install handcart. To hack on it, see CONTRIBUTING.md.

Coming from blinkit-tool? See MIGRATING.md.

Platforms

handcart platforms prints this for your machine, with each platform's login and delivery address. A platform only advertises what it can actually do, so commands it doesn't support don't appear in --help for it, and a fan-out that skips it says so.

CLI

Leave the platform out and the command fans out across every platform; name one to narrow it.

handcart search "amul taaza 500ml"      # every platform, grouped and price-compared
handcart zepto search paneer            # just Zepto
handcart cart                           # every cart you have open
handcart orders                         # merged, newest first
handcart whoami                         # login + delivery address per platform
handcart doctor                         # what isn't ready, and the command that fixes it
handcart location 560034                # one pincode, applied to every platform

Writes and anything needing a platform-specific product id always name the platform:

handcart zepto login 98xxxxxxxx         # SMS OTP
handcart zepto address use home         # label, id, or part of the address
handcart zepto cart add <id> -q 2
handcart zepto checkout                 # payable bill for that address
handcart zepto pay --confirm 642        # the exact amount checkout showed

Every listing command takes --json. handcart <command> --help lists all options.

Cross-platform search

handcart search groups what it believes is the same product and marks the cheapest in-stock row with *, followed by a paste-ready add command for that row. Product ids stay visible because every write takes a platform plus that platform's own id — there is deliberately no "add row 3" shorthand, since a remembered row number means something different tomorrow and the next step spends money.

• --by-platform skips grouping and prints one plain list per platform.

• --json always returns ungrouped results tagged with platform, plus an errors array, so a machine consumer is never misled by a grouping decision.

• A group the matcher isn't sure about is marked [uncertain match] rather than merged silently.

Grouping affects display only. See Matching.

Sold-out products

Blinkit's search never returns sold-out products, and category listings put them at the very end, so by default you mostly see what's in stock. Pass --out-of-stock (-o) to search or browse (MCP: includeOutOfStock: true) to also list sold-out items, tagged [OUT OF STOCK] / inStock: false, after the in-stock ones.

Paying

handcart <platform> pay --confirm <rupees> places the order and waits for the UPI payment (10 minutes by default). How the QR reaches the payer is set with --handoff:

If qrbaton can't be reached, pay falls back to the plain QR and says so. The QR PNG is always saved under ~/.cache/handcart/.

Other options: --no-open prints the link / QR path instead of opening it, --agent <name> shows who prepared the order on the pay page, --dry-run stops before a QR is generated.

qrbaton never handles money, but anyone with a pay link can see the order, including the delivery address. Use --handoff qr if you don't want that.

Matching

Deciding that Blinkit's Amul Gold Milk and Zepto's Amul Gold Homogenised Standardised Milk (Tetra Pack) are the same thing is the hard part, and neither platform exposes a barcode. Handcart does it with no dependencies, no model and no network, in under a millisecond:

1. Quantity, as a hard gate. 500 ml, 1 ltr, 1 pack (500 ml), 6 pcs, 2 x 500 ml all normalise to a value and a class, and a mismatch can never group. This is what stops a 1 L carton looking cheaper than a 500 ml pouch.

2. Brand gate. Two known-but-different brands never group.

3. Name similarity plus MRP. Maximum Retail Price is printed on the pack by law and is the same in every store, which makes it the strongest signal available. Hindi-English and spelling variants are collapsed first (dahi/curd, namak/salt, arhar/toor, iodised/iodized).

4. Mutual-best assignment, so each product claims at most one counterpart on another platform.

Measured against 1,200 real products captured from both platforms over 30 queries, hand-labelled, in test/fixtures/match/: 97.1% precision, 97.1% recall. npm run bench:match reproduces it, and it and npm test fail below 97% precision or 95% recall. Every remaining mistake is marked [uncertain match].

MCP server (Claude, Cursor, Grok…)

{
  "mcpServers": {
    "handcart": {
      "command": "npx",
      "args": ["-y", "handcart", "mcp"]
    }
  }
}

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart Claude

• Claude Code: claude mcp add handcart -- npx -y handcart mcp

• Cursor: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

• Grok CLI: grok mcp add handcart -- npx -y handcart mcp

Run handcart setup once from a terminal, or let the agent log in with the OTP tools. The server runs on your machine, so cloud-only agents can't reach it.

Agent flow

Handcart-level tools (doctor, platforms, search, cart, orders, whoami) cover every platform; per-platform tools are <platform>_<verb>.

doctor → platforms → (login: <p>_login_request_otp, <p>_login_verify_otp) → <p>_use_address → search → <p>_cart_set → <p>_checkout → user confirms the amount → <p>_pay → poll <p>_pay_status until qr_ready → send the user payLink (or, with handoff: "qr", the QR image).

The instructions tell agents never to request an OTP for a number the user didn't give, and never to call a pay tool without explicit confirmation of the exact amount from checkout.

Library

import { Blinkit, client, platforms, group } from "handcart";

// Platform-neutral: whatever is registered
for (const p of platforms()) console.log(p.name, p.capabilities);
const zepto = client("zepto");
const found = await zepto.search("milk", { limit: 5 });
await zepto.add(found[0].id, 2);

// Compare across platforms yourself
const tagged = found.map((p) => ({ ...p, platform: "zepto" }));
for (const g of group(tagged))
  console.log(
    g.title,
    g.offers.map((o) => `${o.platform} ₹${o.price}`),
  );

// Or reach for one platform's full client
const bk = new Blinkit();
await bk.setLocation({ pincode: "560034" });
await bk.catalog.search("milk", { sort: "price", inStock: true, limit: 5 });

Configuration

Sessions and cookies live in ~/.config/handcart/, owner-readable only; caches in ~/.cache/handcart/. The pre-rename BLINKIT_* names still work with a deprecation notice, and directories left behind by blinkit-tool are moved across on first run so you don't have to log in again.

Troubleshooting

Run handcart doctor first — it names the command that fixes each ✗.

• "refusing automated requests": Cloudflare or Zepto's WAF is challenging the request. Wait a few minutes and retry.

• "session expired or not logged in": handcart <platform> login <phone>.

• Prices look wrong next to each other: the platforms are probably set to different addresses. handcart whoami, then handcart location <pincode>.

• Search doesn't show something you expected: it may be sold out; retry with --out-of-stock.

• pay says the amount differs: the bill changed (stock, charges, promo). Re-run checkout and confirm the new amount.

Development

Project layout, scripts and how to run from source (npm run dev, npm run mcp) are in CONTRIBUTING.md.

Contributing

Issues and PRs welcome: see CONTRIBUTING.md. Please follow the Code of Conduct, and report security problems privately as described in SECURITY.md. Never paste your session files, cookie jars, OTPs, or pay links into an issue.

License

MIT