# Quantum Bear MicroAPI buyer client

Node.js 22 or later. This client calls the six existing Quantum Bear APIs on **Base mainnet**, using your own USDC wallet. It contains public service terms only. It does not load the seller's keys, CDP credentials or test wallets.

## Inspect a price without paying

```sh
node call.mjs json-structure examples/json-structure.request.json
```

This command makes one unpaid POST and prints its checked terms. It does not read a key or sign anything. Quote-only mode works without npm dependencies. Other operation IDs are `csv-preflight`, `dns-records`, `email-domain`, `x402-preflight`, `http-tls`.

## Make one paid call

```sh
npm ci --ignore-scripts --no-audit --no-fund
export X402_PRIVATE_KEY_FILE=/absolute/path/to/your-protected-key.txt
node call.mjs json-structure examples/json-structure.request.json --pay --max-usdc 0.003
```

The key file must contain your own 0x-prefixed EVM private key; protect it with mode 0600 and keep it out of the project. The CLI never prints it. Fund that wallet with native USDC on Base. The x402 facilitator settles the authorization; the client sends no separate gas transaction or direct transfer.

The payer must explicitly supply both `--pay` and a per-order `--max-usdc`. Payment terms must exactly match `terms.json`: resource, network, native USDC contract, receiver and price. Prices currently range from 0.003 to 0.01 USDC. A price or receiver change stops the client for review. Validation findings such as `valid=false` are useful paid results.

Results go to stdout with HTTP status, the server's settlement receipt, confirmation label and local order-state path. `independentChainReceiptVerified` remains false: the client reports the server receipt and does not claim to have independently checked the blockchain. For a payment dispute, verify the transaction on Base and compare recipient, token and amount.

## Repeated orders and uncertain outcomes

Before signing, the client reserves an order file in `.quantum-bear-orders/` (directory 0700, files 0600). It records the input hash, price, nonce, state and available receipt; it does not record your input or signature. Keep this directory across restarts. An identical input to the same operation is blocked on a repeated invocation, including after a timeout. Do not delete a pending file to retry.

For an intentional new purchase of the same input, explicitly use a new ID:

```sh
node call.mjs dns-records examples/dns-records.request.json --pay --max-usdc 0.005 --order-id scheduled-check-002
```

Use `--state-dir /protected/persistent/directory` to keep order state elsewhere. Separate state directories or IDs are separate orders and may each spend money. A timeout or malformed response can occur after settlement: inspect the existing nonce/receipt and reconcile before another purchase. The server does not retain request files or computed results, so it cannot automatically restore a lost response. Refund or service recovery needs separate operator review.

## Verification and limitations

```sh
node --test client.test.mjs sdk.test.mjs
```

Tests use clearly synthetic payment fixtures and a stub signer. They never transmit a signed authorization or use a funded key. Live quote checks do not test a newly paid call or establish customer demand. Prior full server payment tests are recorded separately in the project reports.

Official protocol references: [x402 client configuration](https://docs.cdp.coinbase.com/x402/buyer/client-configuration), [x402 source](https://github.com/x402-foundation/x402). Dependencies are pinned in package-lock.json. This is a focused single-order client, not a wallet backup tool or automatic purchase loop.