JustHandled Agent Utility Gateway
Thirty-two guarded agent utilities and maintained-data lookups over USDC x402.
Open source Open in the app JSON README (API)
About
Thirty-two guarded agent utilities and maintained-data lookups over USDC x402.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- justhandledlabs
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.11.1
- Last push
- 2026-08-02T04:16:31Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:18
- Updated
- 2026-08-29 04:00:18
- Origin id
io.github.justhandledlabs/agent-gateway
README
# JustHandled Agent Client
A guarded CLI, JavaScript client, and local MCP server for the [JustHandled Agent Utility Gateway](https://justhandledlabs.com/agent-gateway/). The package exposes thirty-two preflights, maintained-data lookups, and evidence products. Twenty-two products cost $0.05 USDC; ten evidence-heavy or maintained-data products cost $0.25, including the live Chicago Contract Change Packet. Every paid call returns a versioned evidence receipt.
The client fails closed before signing. It accepts only the pinned JustHandled gateway, Base mainnet, canonical Base USDC, the exact per-product price, and the published merchant receiver. Customer inputs and complete customer results are not persisted by the gateway; maintained public-source snapshots are labeled in the receipt.
## Inspect without a wallet
```bash
npx --package @justhandledlabs/agent-client justhandled-agent catalog
npx --package @justhandledlabs/agent-client justhandled-agent preview filename-portability-preflight --json '{"paths":["CON.txt"]}'
npx --package @justhandledlabs/agent-client justhandled-agent preview agent-run-evidence-pack --file agent-run-evidence-pack.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview agent-distribution-readiness-pack --file agent-distribution-readiness-pack.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview community-rule-credibility-preflight --file community-rule-credibility-preflight.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview qualified-demand-ledger --file qualified-demand-ledger.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview channel-fit-evidence-matrix --file channel-fit-evidence-matrix.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview proof-to-channel-evidence-packet --file proof-to-channel-evidence-packet.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview channel-experiment-postmortem --file channel-experiment-postmortem.sample.json
npx --package @justhandledlabs/agent-client justhandled-agent preview chicago-contract-change-packet --file chicago-contract-change-packet.sample.json
```
Preview performs an unpaid request and validates the returned x402 terms. It does not sign or spend.
The catalog includes API-response contract drift, webhook contract and replay, and policy-change evidence products. Packaged example inputs are available in `examples/`.
Machine-readable products, exact payment terms, and free deterministic fixtures are available from the gateway's [product catalog](https://justhandled-agent-gateway.netlify.app/api/product-catalog), [OpenAPI document](https://justhandled-agent-gateway.netlify.app/openapi.json), and [sandbox index](https://justhandled-agent-gateway.netlify.app/sandbox/index.json).
## Execute one paid utility
Use a dedicated low-balance Base wallet. Never provide a primary wallet key.
```bash
export JH_EVM_PRIVATE_KEY=0x...
npx --package @justhandledlabs/agent-client justhandled-agent call filename-portability-preflight --json '{"paths":["CON.txt"]}'
```
PowerShell:
```powershell
$env:JH_EVM_PRIVATE_KEY = "0x..."
npx.cmd --package @justhandledlabs/agent-client justhandled-agent call filename-portability-preflight --json '{"paths":["CON.txt"]}'
```
## MCP configuration
```json
{
"mcpServers": {
"justhandled": {
"command": "npx",
"args": ["-y", "@justhandledlabs/agent-client"],
"env": {
"JH_EVM_PRIVATE_KEY": "0xDEDICATED_LOW_BALANCE_WALLET_KEY"
}
}
}
}
```
The MCP server exposes a free catalog tool plus one paid tool per gateway utility. Missing wallet configuration produces an error instead of a payment attempt.
The package declares the official MCP Registry identity `io.github.justhandledlabs/agent-gateway`. Registry identity is discovery metadata only: installing or listing the server does not spend funds, and paid execution still requires a dedicated wallet plus the client's exact-term checks.
## Security model
- Price, chain, asset, receiver, and gateway origin are pinned in code.
- The ten $0.25 products' 250,000-base-unit price is pinned separately from 50,000-base-unit checks.
- Every execution starts with an unpaid 402 preview.
- A mismatched term aborts before signing.
- The package never prints the private key.
- The gateway does not persist customer inputs or complete customer results. Maintained-data products may retain normalized public-source snapshots and disclose that state in the receipt.
- Treat all crypto transfers as irreversible and fund only a dedicated wallet.
## Development
```bash
npm install
npm run check
```
The gateway implementation is intentionally not included in this client repository.