# JustHandled Agent Integration Guide

JustHandled sells deterministic preflight and evidence checks to software agents. Discovery and fixed sandbox fixtures are free. Live execution costs $0.05 USDC per call through x402 on Base mainnet.

## Choose an integration

1. Use `@justhandledlabs/agent-client` over stdio for MCP clients that can provide a dedicated Base wallet private key. The client previews every payment challenge and refuses any network, asset, amount, receiver, or gateway mismatch before signing.
2. Use the OpenAPI document or product catalog with an x402-aware HTTP client for direct calls.
3. Use the hosted `/mcp` route for stateless MCP discovery. Paid tool calls on that route return the corresponding x402 HTTP endpoint; hosted MCP does not hold or operate a buyer wallet.

## Discovery order

- `/api/product-catalog` for exact commerce terms and products
- `/openapi.json` for request schemas and operations
- `/sandbox/index.json` for free deterministic request fixtures
- `/api/schema/:utility` for one input schema
- `/.well-known/mcp/server-card.json` for MCP transport behavior

## Payment sequence

1. POST JSON to `/api/run/:utility` without a payment signature.
2. Require HTTP 402 and inspect the `Payment-Required` header.
3. Verify Base mainnet, canonical Base USDC, 50,000 base units, the published JustHandled receiver, and the exact requested resource.
4. Sign only after those checks pass.
5. Retry with the x402 payment header.
6. Require HTTP 200 plus a settlement header, then retain the evidence receipt.

## Guardrails

- Never send a wallet private key to the gateway.
- Never infer downstream success from `READY`; it is a bounded preflight verdict.
- Treat a payment challenge as an offered transaction, not proof of demand or revenue.
- Raw inputs and results are not persisted. See `/telemetry.md` for the separate commercial-event policy.
- Use a dedicated, minimally funded agent wallet and enforce your own spending budget.

## Compatibility

Gateway API version: 0.2.0. Evidence schema version: 1.0. MCP protocol version: 2025-06-18.

See `/authentication.md`, `/versioning.md`, `/limits.md`, `/errors.md`, and `/support.md` for operational details.