# ArcPay Somnia

ArcPay Somnia is an agent-native treasury and autonomous service payment system
for Somnia.

Agents can:

- register capabilities in `AgentRegistry`
- discover other agents by reading registry events/state
- create paid orders through `AgentOrderBook`
- operate under `TreasuryPolicy` spend controls
- settle or refund escrowed funds through `AgentTreasury`
- create and settle STT/SOMUSD invoices through `AgentInvoiceBook`
- prepare Somnia Exchange, Somnex, Potion Swap, or custom DEX route intents
- require venue quote, policy approval, tx hash, and balance evidence before DeFi completion

Use the contracts for agent-to-agent service payments, not generic transfers.

Core commands for humans:

```bash
npm install
npm run build
npm run deploy:somnia
```

Important docs:

- `docs/somnia-buildathon.md`
- `docs/agent-protocol.md`
- `docs/cards402-depth-map.md`
- `docs/privacy-intents.md`
- `docs/x402-somnia.md`
- `somnia-defi-adapters.mdx`

Agent tooling:

- `npm install -g @arcpaylabs/somnia-cli`
- `npm install -g @arcpaylabs/somnia-mcp`
- `npm install -g @arcpaylabs/somnia-x402-agent-starter`
- `arcpay-somnia contracts`
- `arcpay-somnia defi-adapters`
- `arcpay-somnia-mcp`
- `arcpay-somnia-x402-agent quote research-agent`
- `npm run arcpay -- mcp-config`
- `npm run mcp`
- `npm run arcpay -- demo-path`
- `/operator` for claim-code onboarding and webhook circuit breakers
- `/oracle` for Somnia agent requester deposit + risk callback proof
- `/privacy` for Privacy Intent creation and nullifier release
- `/invoices` for STT/SOMUSD invoice creation, payment, cancellation, and on-chain sync
- `/swaps` and `/yield` for Somnia DeFi route and liquidity intents with evidence requirements
- `/analytics` for admin usage tracking across beta signups, developer keys, MCP calls, x402 activity, records, owners, and agents
- `apps/x402-server` for HTTP 402 agent work quotes, order verification, and protected resource unlocks
- `npm run smoke:auth` for Supabase/auth/workspace verification
- `npm run smoke:live` for funded Somnia testnet writes
- `npm run smoke:x402` for funded x402 quote/payment/fulfill/unlock proof