@loopprotocol/sandbox-cli — Loop Protocol Sandbox CLI

Operational tool for partner integrators. Goes from clone to a live BYOAA disbursement on the Loop Protocol sandbox in under 5 minutes — and stays useful after that for every step of the merchant / vault / receipt / claim lifecycle.

Status: v0.3.1 — full command surface live on devnet. Pre-mainnet alpha; protocol may change before mainnet.

Install

npm i -g @loopprotocol/sandbox-cli
loop-sandbox --help

Or no-install:

npx @loopprotocol/sandbox-cli quickstart

The 5-minute demo

loop-sandbox quickstart --key sk_test_your_key

Generates a partner wallet → funds it → registers a sandbox merchant → initializes a vault → records a $10 attested receipt → honors it → prints the 80/14/6 disbursement with Solscan links for every tx.

Full command surface

Read-only / no auth:
  status                         sandbox health probe
  whoami                         API key partner label + remaining daily quotas
  merchant list                  list all sandbox merchants
  merchant show <id>             full merchant details
  merchant claimable-names       list registered name variants per merchant
                  [--id N]
  merchant resolve <name>        which merchant_ids would claim this receipt name
  vault list [--owner X]         list sandbox vaults
  vault show [pubkey]            vault account state
  vault balance [pubkey]         vault Cred balance
  receipt list [--vault X]       list attested receipts
  receipt show <pda>             full receipt details
  session list [--vault X]       list registered sessions
  claim-pending [--vault X]      receipts eligible to honor
                [--merchant id]
  claim-sweep [--vault X]        honor every pending receipt that auto-resolves
              [--merchant id]    (use --dry-run to preview)
              [--max N]
              [--dry-run]
  tx <signature>                 pretty-print a Solana tx with Solscan link

Wallet (local):
  wallet generate [--out path] [--force]
  wallet import <src> [--out path]
  wallet show [--json]
  wallet balance [pubkey]        SOL/USDC/CRED balances

Faucet (auth required):
  fund <pubkey> --sol N --usdc N --cred N

Merchant lifecycle (admin- or partner-signed):
  merchant register --name N --category C [--rate bps] [--signing-pubkey pk]
  merchant set-window <id> --seconds N
  merchant set-names <id> --names "Acme,ACME COFFEE,Acme Co"
  merchant fund-pool <id> --amount N

Vault + sessions (partner-signed):
  vault init
  session register --vault X [--session-key Y]
  session revoke <session-pda>

BYOAA flow (mixed signers):
  receipt submit --vault X --bank-id Y --name "..." [--mcc N] [--amount $] [--posted-at T]
  claim <receipt-pda> [--merchant id]   honor a receipt; auto-resolves merchant
  capture-mint --vault X --amount N [--type T] [--source label]   alt mint flow

Global flags

| Flag | Env var | Default | |---|---|---| | --api <url> | LOOP_SANDBOX_API | https://sandbox.looplocal.io | | --key <key> | LOOP_SANDBOX_KEY | (none — required for auth'd commands) | | --wallet <path> | LOOP_SANDBOX_WALLET | ./loop-sandbox-quickstart.json | | --json | LOOP_SANDBOX_JSON=1 | (off) |

Resolution: flag → env var → ~/.loop/config.json → built-in default.

Persistent defaults

loop-sandbox config set api https://sandbox.looplocal.io
loop-sandbox config set key sk_test_your_key
loop-sandbox config set wallet ~/.loop/sandbox-wallet.json
loop-sandbox config show

Config lives at ~/.loop/config.json (or LOOP_SANDBOX_CONFIG=... to override). API key is masked in config show output but stored plaintext on disk with mode 0600.

Shell completion

# Bash: one-shot
source <(loop-sandbox completion bash)

# Bash: persistent
loop-sandbox completion bash > /etc/bash_completion.d/loop-sandbox

# Zsh: persistent
loop-sandbox completion zsh > "${fpath[1]}/_loop-sandbox"

Static completion of commands + subcommands + global flags. Doesn't auto-complete merchant_ids or vault PDAs (would require an RPC round-trip per TAB).

--json switches every command to structured stdout output, suppressing human-formatted lines. Errors emit a JSON envelope on stderr. Designed for scripting partners who pipe to jq or build their own dashboards.

loop-sandbox --json claim-pending --vault $VAULT | jq -r '.pending[].pda' | \
  xargs -n1 loop-sandbox --json claim --merchant 7 | jq '.disbursement'

Authentication

v0 alpha integrators get an API key from Loop staff. Set it once:

export LOOP_SANDBOX_KEY=sk_test_your_key

Read-only commands (status, merchant list/show, vault show/balance, receipt list/show, session list, claim-pending, tx) work without an API key.

Workflow recipes

Stand up a sandbox merchant from scratch:

loop-sandbox wallet generate
loop-sandbox fund $(loop-sandbox wallet show --json | jq -r .pubkey) --sol 1 --cred 5
loop-sandbox merchant register --name "Acme Coffee" --category FoodBeverage --rate 150
loop-sandbox merchant set-window <id> --seconds 7776000
loop-sandbox merchant set-names <id> --names "Acme Coffee,ACME COFFEE,ACME COFFEE LLC"
loop-sandbox merchant fund-pool <id> --amount 5

Sweep all pending claims for your merchant:

loop-sandbox claim-sweep --merchant 7 --dry-run    # preview first
loop-sandbox claim-sweep --merchant 7              # then honor

The sweep prefetches the merchant-name index once (one RPC) and resolves each receipt locally — fast even with hundreds of pending claims. Pair with cron or a queue worker for ongoing operation.

Inspect a transaction without leaving the terminal:

loop-sandbox tx 4knwDY...GhmI

Directory layout

scripts/sandbox/cli/
├── README.md
├── package.json                 npm package metadata + bin entry
├── src/
│   ├── cli.ts                   commander dispatch + global flags
│   ├── commands/                one file per command surface
│   │   ├── quickstart.ts        end-to-end demo
│   │   ├── status.ts whoami.ts wallet.ts fund.ts tx.ts
│   │   ├── merchant.ts vault.ts session.ts
│   │   ├── receipt.ts claim.ts capture-mint.ts
│   └── lib/
│       ├── api-client.ts        HTTP client + typed endpoint wrappers
│       ├── context.ts           global flag → CommandContext resolution
│       ├── solana.ts            RPC + on-chain ix construction (IDL.address pin)
│       ├── ui.ts                human + JSON output (header/info/success/emitJson)
│       └── wallet.ts            keypair generation + JSON storage
├── idls/                        bundled IDLs (loop_vault, loop_shopping)
└── docs/                        partner-facing guides (linked below)

Build + publish

cd scripts/sandbox/cli
npm install
npm run build       # tsc → dist/
npm publish --access public

Partner-facing docs (in docs/)

• docs/quickstart.md — your first 5 minutes, annotated
• docs/api-reference.md — endpoint specs with curl + TS examples
• docs/integration-patterns.md — three patterns (PoS vendor, BYOAA bank, agent service) with full code
• docs/troubleshooting.md — common errors + on-chain debugging
• docs/sandbox-vs-mainnet.md — what's the same, what's different, how to migrate

Internal docs

• ~/dev/loop/loop-coordination/sandbox-runbook-v0.md — full architecture
• scripts/sandbox/proxy/README.md — the Vercel proxy services
• scripts/devnet-rehearsal/test-spec08-09-flow-devnet.ts — BYOAA reference flow