# Connect a buying agent in five minutes

This quickstart is for teams building sourcing, procurement or supply-chain agents. The sandbox uses structured fastener data so you can validate tool calls before requesting a production API key.

## 1. Run locally

```powershell
cd outputs/api
npm start

# New terminal
cd outputs/mcp
npm install
npm start
```

The default MCP stdio server uses `http://127.0.0.1:8787`. Product search and detail requests in demo mode accept `PAYMENT_SIGNATURE=mock-valid`; they do not create an on-chain charge.

## 2. Configure an MCP client

Add this configuration to an MCP-compatible client:

```json
{
  "mcpServers": {
    "buyingmesh": {
      "command": "node",
      "args": ["C:/path/to/outputs/mcp/sdk-server.mjs"],
      "env": {
        "API_BASE_URL": "http://127.0.0.1:8787",
        "PAYMENT_SIGNATURE": "mock-valid"
      }
    }
  }
}
```

For a remote environment:

```json
{
  "url": "https://buyingmesh.com/mcp"
}
```

Production use requires HTTPS, an API key, rate limits and a real x402 verifier. Never send the demo signature to production.

## 3. Recommended call order

1. `search_products`: filter with `q`, `minMoq`, `maxPrice` and `limit`.
2. `get_product`: check `dataFreshness`, `confidence`, supplier qualifications and inventory.
3. `compare_quotes`: send SKU, quantity and destination.
4. Show the buyer price and lead time, then call `create_order` after approval.
5. Use `get_order_status` or signed webhooks for shipment, tracking, ETA, delivery and escrow release.

## 4. Try the API in 30 seconds

```powershell
$h = @{ 'PAYMENT-SIGNATURE' = 'mock-valid' }
Invoke-RestMethod 'http://127.0.0.1:8787/v1/products?q=M4&limit=5' -Headers $h
```

Without a payment signature, the API returns `402 Payment Required` and includes an x402 requirement in the `PAYMENT-REQUIRED` header. An x402-aware agent can replay the request after payment.

## 5. Trust checks before production

- Every product has a source, update time, confidence and supplier qualification state.
- Quotes and orders use idempotency keys, so retries do not create duplicates.
- Webhooks use an `X-YW-Signature` HMAC and record delivery and retry state.
- Order status follows a strict state machine.
- Price, inventory and lead time are time-sensitive snapshots.

## 6. Request more data

The sandbox starts with standard fasteners. Production onboarding can connect authorized marketplace exports, merchant-owned catalogs or supplier data from the network. BuyingMesh keeps the source reference and publishes a normalized Schema.org JSON-LD record.

## 7. Merchant onboarding

Merchants can submit a profile at `/merchant.html`. After receiving an `applicationId`, send a small CSV-derived product sample to `POST /v1/merchant/products/import`. Imported rows remain `pending_review` until an operator approves the record.

The CSV template is available at `/merchant-template.csv`.