# BlockLabs Catalog

> x402-payable dropshipping shop for AI agents and humans. 300,000+ physical
> products, paid per-call in USDC (Base mainnet or Solana), shipped to EU
> member states only. No accounts, no API keys - every request is paid with
> an x402 payment signature.

## API (x402 v2)

- GET https://shop.blocklabs.nl/api/search?q=...&page=1&per_page=20&iso=en
  Full-text, typo-tolerant product search. $0.001 USDC per query.
  Returns SKUs, names, EUR prices, live stock, image URLs.
- GET https://shop.blocklabs.nl/api/product?ref=<id|sku>&iso=en
  Full product detail by catalog id or SKU: description, prices, live stock,
  all images, taxonomy, manufacturer. $0.001 USDC per lookup.
- GET https://shop.blocklabs.nl/api/taxonomies?parent=<id>&iso=en
  Browse the category tree (roots without parent); every node carries total
  and live in-stock product counts. $0.001 USDC per call.
- POST https://shop.blocklabs.nl/api/shipping-options
  All shipping options (carrier, cost, delay) for a basket to an EU address;
  pass the chosen carrier into the order. $0.001 USDC per call.
- POST https://shop.blocklabs.nl/api/order
  Place a dropshipping order. Unpaid request returns HTTP 402 with a signed
  all-in USD quote (items + shipping + taxes) in the payment-required header;
  pay the quote to place the order. shippingAddress.country must be an EU
  member state ISO code.
- GET https://shop.blocklabs.nl/api/orders/{reference}
  Free order status: payment, fulfillment state, carrier tracking.
- GET https://shop.blocklabs.nl/health
  Free liveness probe.

Payment: x402 "exact" scheme (EIP-3009 USDC), networks eip155:8453 (Base)
and solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp. Facilitator: PayAI. Signed
offers and receipts (EIP-712) on every transaction. Discovery declarations
(bazaar extension) with full JSON Schemas are embedded in every 402 response.

## MCP server

npm: @blocklabs/shop-mcp - mount the shop as MCP tools (search_products, get_product, get_shipping_options, browse_categories,
get_order_quote, place_order, track_order, shop_info) in Claude Desktop,
Claude Code, or any MCP client. Node >= 22; wallet key via EVM_PRIVATE_KEY.

Claude Desktop (claude_desktop_config.json) / Claude Code (.mcp.json):

    {
      "mcpServers": {
        "blocklabs-shop": {
          "command": "npx",
          "args": ["-y", "@blocklabs/shop-mcp@latest"],
          "env": {
            "EVM_PRIVATE_KEY": "0x<funded USDC wallet on Base>",
            "MAX_ORDER_USD": "50"
          }
        }
      }
    }

Omit EVM_PRIVATE_KEY to use the free tools only (quotes, tracking, info).

## Notes

- EU-only shipping (27 member states), enforced at validation and declared
  in the published order schema.
- Quotes are free: POST /api/order unpaid and read the 402.
- Search results include catalog product ids usable for order references.