# SolMachina — the trust & decision layer for Solana agents (x402)

The flagship is **/v1/decision**: before your agent moves money, ask SolMachina and get EXECUTE / REVIEW /
REJECT + an SMRI risk score (0-100) + evidence + a signed receipt in one call — plus an optional policy
firewall (send minSmri/denyMintAuthority… → ALLOW/DENY, fail-closed). Trust-first: cites every source,
says "unknown" over guessing; every paid answer is signed and verifiable offline.

You can buy structured Solana intelligence from this API without an account or API key:
each paid endpoint answers HTTP 402 with machine-readable USDC payment terms; you sign,
retry, and receive the data in one round trip. Settlement is USDC on Solana mainnet via x402 v2.

## Base URL
https://api.solmachina.com

## Free (no payment)
- `GET /health` — liveness, version, WAL ledger head (sha256), request metrics
- `GET /uptime` — status, latency p95, WAL age, kill-switch state
- `GET /ledger?limit=<n>` — last n ledger entries (default 400, max 1000) for client-side chain verification
- `GET /.well-known/x402` — x402 v2 discovery manifest (prices in atomic USDC units)
- `GET /openapi.json` — OpenAPI 3.1 spec with x-x402 price extensions
- `GET /llms.txt` — LLM-oriented catalog
- `GET /` — human storefront with a live console

## Paid endpoints (pay per call, exact USDC, Solana mainnet)

| Endpoint | Price | Atomic units |
|---|---|---|
| `GET /v1/batch/token-risk?mints=<string>` | $0.10 | 100000 |
| `GET /v1/decision?mint=<string>?action=<string>?amountUsd=<string>?minSmri=<number>?maxConcentrationPct=<number>?minConfidence=<number>?denyMintAuthority=<boolean>?denyFreezeAuthority=<boolean>?denyHighRiskBand=<boolean>?policy=<string>` | $0.05 | 50000 |
| `GET /v1/dex-quote?inputMint=<string>?outputMint=<string>?amount=<string>?slippageBps=<integer>` | $0.003 | 3000 |
| `GET /v1/epoch?rate=<string>` | $0.001 | 1000 |
| `GET /v1/kamino/markets?limit=<integer>` | $0.001 | 1000 |
| `GET /v1/new-pairs?limit=<integer>` | $0.005 | 5000 |
| `GET /v1/nft-collection?symbol=<string>` | $0.003 | 3000 |
| `GET /v1/pretrade?mint=<string>` | $0.10 | 100000 |
| `GET /v1/priority-fee?accounts=<string>` | $0.002 | 2000 |
| `GET /v1/sgp-checkpoint?n=<integer>` | $0.005 | 5000 |
| `GET /v1/simulate?tx=<string>` | $0.01 | 10000 |
| `GET /v1/slippage-map?inputMint=<string>?outputMint=<string>?amount=<string>?slippageBps=<integer>?mults=<string>` | $0.005 | 5000 |
| `GET /v1/smri?mint=<string>` | $0.01 | 10000 |
| `GET /v1/tipfloor?fresh=<boolean>` | $0.001 | 1000 |
| `GET /v1/token-holders?mint=<string>` | $0.005 | 5000 |
| `GET /v1/token-intel?mint=<string>` | $0.05 | 50000 |
| `GET /v1/token-risk?mint=<string>` | $0.028 | 28000 |
| `GET /v1/trending-tokens?limit=<integer>` | $0.005 | 5000 |
| `GET /v1/tx-inspect?sig=<string>` | $0.01 | 10000 |
| `GET /v1/wallet-scan?address=<string>` | $0.02 | 20000 |

All paid endpoints accept a single query parameter (see /openapi.json for schemas) and return
JSON with a disclaimer, methodology and per-field RPC sources. First request of the day from the
storefront demo is a free truncated preview; agents get the standard 402 challenge instead.

## How to pay (x402 v2, scheme=exact, SVM)
1. `GET` the endpoint → 402 with a `payment-required` header (base64 JSON: `accepts[]` with
   `scheme=exact`, `amount` in atomic USDC units, `payTo`, `network=solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`,
   `extra.feePayer` = our facilitator).
2. Build an exact-USDC SVM payment payload with any x402 client (`@x402/svm/exact/client` + `@x402/core/client`).
3. Retry the request with the payload in the `X-PAYMENT` (or `PAYMENT-SIGNATURE`) header, base64-encoded.
4. 200 + `payment-response` header = settled; the payment is appended to the SHA-256-chained ledger
   (`/ledger`, verifiable with any SHA-256 implementation).

## Honesty doctrine (read before integrating)
- Responses NEVER fabricate confidence: undeterminable values are `"unknown"`, never guessed.
- No "safe"/"scam"/"buy"/"avoid" verdicts anywhere — factual, threshold-stated signals only.
- Every sub-analysis that failed is an explicit error field, never silent.

## MCP
The catalog is also exposed as paid MCP tools — public npm package:
`npx solmachina-x402-mcp@1.1.0` (Claude Code: `claude mcp add solmachina -s user -- npx -y solmachina-x402-mcp@1.1.0`).

## Operator
MEGATRON / SolMachina · payTo: HGLdAaCYcy98HsjLypcfaMjgQLujXEKfrbWc3MhrfNdG · Not financial advice.