Quickstart

Quickstart

Pick the path that matches what you are trying to do.

Send a boon from the web app

Use this when a human wants to send one thank-you now.

1. Open boonprotocol.com/send.
2. Enter a canonical handle such as github:alice or x:bob.
3. Enter a small USDC amount and a short evidence-backed note.
4. Connect Coinbase, Metamask/injected, or WalletConnect.
5. If the wallet is short on Base USDC, use the Coinbase Onramp prompt.
6. Approve exactly the displayed USDC amount if needed, then send.

The browser wallet signs the transaction. The onramp funds the wallet; it does not atomically call Boon.tip().

Claim a boon

Use this when someone sent you a Boon receipt or told you a handle has funds waiting.

1. Open boonprotocol.com/claim.
2. Sign in with the GitHub or X account that received the boon.
3. Review the proven handle and claimable amount.
4. Choose Coinbase, Metamask/injected, or WalletConnect as the receiving wallet.
5. Confirm the permanent v1 link from handle to wallet.
6. If the relayer is enabled, Boon submits link and claim transactions. If not, the UI fails loudly instead of pretending claim completed.

Try the CLI safely

Use this when an agent or operator wants to preview a proposed tip without moving funds.

boon doctor
boon wallet connect ows --wallet boon-agent
boon tip --dry-run github:alice 2 "pr:owner/repo#42 — helpful review"

Live CLI sends require a connected, funded OWS wallet and either an interactive approval prompt or --yes --approval-id <human-approved-plan-id>.

Verify public API health

curl https://api.boonprotocol.com/health
curl https://api.boonprotocol.com/api/v1/points/policy
curl https://api.boonprotocol.com/api/v1/handles/github:alice/points

The detailed per-handle boon list is x402-paid:

curl -i 'https://api.boonprotocol.com/api/v1/handles/github:alice/boons?limit=1'

An unpaid request should return 402 Payment Required with a PAYMENT-REQUIRED challenge.

Local repo smoke

git clone --recurse-submodules https://github.com/velinussage/boon
cd boon
pnpm install
forge test -vvv
pnpm --filter @boon/normalize test
pnpm --filter boon-worker test
pnpm --filter boon-cli test

Fork tests, signer roundtrip tests, deployments, and live paid x402 settlement require environment-specific keys or RPC settings.