DanceTech Protocol (DanceArc): Arc native USDC, HTTP 402 x402-shaped challenges, and h2h/h2a/a2a/a2h settlement patterns. Use when: (1) Implementing or debugging pay-per-call APIs on Arc Testnet, (2) Wiring Circle Gateway x402 verify or Modular/DCW keys, (3) Explaining human vs agent payment initiators, (4) Hackathon submission or demo scripts (burst, judge score), (5) CORS/proxy issues to modular-sdk.circle.com, (6) Recipient or receipt verification errors.
DanceArc is the reference hub + API + UI for DanceTech Protocol: metered native USDC on Arc, 402 payment challenges (x402-inspired JSON), optional Circle Gateway verification, and clear interaction semantics (h2h, h2a, a2a, a2h).
| Situation | Action |
|---|---|
| Pay-per API call (human wallet) | h2a: POST → 402 → pay Arc USDC → retry with X-Payment-Tx (/dance-extras, /api/judges/score) |
| Battle / coaching / beat license | h2h: create intent or end session → sendNativeUsdc or mock → /verify or with |
/grantpaymentTx| High-frequency micro-txs (demo) | npm run burst (private key) or hub Burst demo (wallet) (55 signatures) |
| Server 500 “receipt not found” right after pay | Server uses waitForTransactionReceipt; increase ARC_TX_RECEIPT_TIMEOUT_MS if needed |
| Circle Modular 403 Lockout | Check Client Key, allowlist localhost (no port), optional CIRCLE_MODULAR_PRESERVE_ORIGIN=1, staging URL vs key |
| Programmatic faucet 403 | Use web faucet; API key may lack faucet scope |
Invalid ARC_RECIPIENT (UUID-style) | Server isAddress validation falls back to demo address; set real 0x + 40 hex |
| Agent needs payee + chain | GET /api/health → recipient, chainId, perActionUsdc |
| Mode | Acronym | Who pays | Who receives | DanceArc surface |
|---|---|---|---|---|
| Human → Human | h2h | Person | Person/treasury (ARC_RECIPIENT) | /battle, /coaching, /beats |
| Human → Agent | h2a | Person (wallet) | API/resource owner | /dance-extras, /api/judges/score |
| Agent → Agent | a2a | Automated signer | Another service | Designed: headless key / smart account; demo: burst scripts |
| Agent → Human | a2h | Service/treasury | Person | Payout mocks, receipts, DCW faucet → user address |
Use this matrix in pitch decks, AGENTS.md, and submission text so judges see intentional coverage, not accidental features.
Manual (recommended until ClawdHub listing is live):
git clone https://github.com/arunnadarasa/dancearc.git
cp -r dancearc/skills/dancearc-protocol ~/.openclaw/skills/dancearc-protocol
After publish to ClawdHub:
clawdhub install dancearc-protocol
Repository: github.com/arunnadarasa/dancearc
Activate proactively when the user mentions:
npm run burst, transaction frequency demoBrowser (Vite) ──proxy /api──► Express (8787)
├── buildArcPaymentChallenge (402)
├── verifyNativeUsdcPayment (viem + waitForTransactionReceipt)
├── circleGatewayPost (/v1/gateway/v1/x402/verify)
├── recordNanopaymentEvent (in-memory list)
└── DCW / Modular proxy routes
On-chain truth: Arc explorer (e.g. https://testnet.arcscan.app).
| Path | Role |
|---|---|
server/index.js | Routes, requireArcPayment, proxies |
server/payments.js | Intents, coaching, beats |
server/onchain-verify.js | Receipt wait + validation |
server/config.js | ARC_RECIPIENT validation (isAddress) |
src/payArc.ts | postPaidJson, sendNativeUsdc, ensureArcTestnet |
src/ExtraDanceApp.tsx | h2a UI + ArcScan link |
src/BattleApp.tsx, CoachingApp.tsx, BeatsApp.tsx | h2h flows |
| Variable | Scope | Purpose |
|---|---|---|
ARC_RECIPIENT | Server | Payee for microtransfers |
PER_ACTION_USDC | Server | h2a minimum (display string, ≤ 0.01 for hackathon) |
CIRCLE_API_KEY | Server | Gateway verify; DCW; faucet |
CIRCLE_ENTITY_SECRET | Server | DCW only |
VITE_CIRCLE_CLIENT_KEY | Browser | Modular SDK |
ARC_BURST_PRIVATE_KEY | Machine | Test only — CLI burst |
Never commit .env. Copy from .env.example.
| Signal | Likely cause | First check |
|---|---|---|
TransactionReceiptNotFoundError | Race before inclusion | Server waitForTransactionReceipt; client retry |
| 403 HTML Lockout (Modular) | Key / domain / WAF | Console allowlist, CIRCLE_MODULAR_PRESERVE_ORIGIN |
invalid_recipient in UI | Bad env | Fix ARC_RECIPIENT, new intent |
| 402 after payment | Wrong recipient/amount/chain | Explorer tx vs challenge payTo / maxAmountRequired |
Faucet Forbidden | Circle policy / scopes | Web faucet link in ArcFaucetPanel |
recordNanopaymentEvent + GET /api/nanopayments/events are an in-memory audit trail after successful on-chain verify—not a substitute for full Nanopayments API integration. Use the narrative + Gateway path for hackathon feedback fields.X-Payment-Tx only after a wallet or custodial signer produces a hash; do not fake hashes for production.scripts/burst-demo.mjs patterns.ARC_BURST_PRIVATE_KEY like production secrets—AGENTS.md should forbid echoing it into browser context.| File | Content |
|---|---|
references/api-routes.md | HTTP route map |
references/payment-flow.md | 402 + verify sequence |
references/openclaw-workspace.md | Suggested AGENTS.md / TOOLS.md snippets |
If you maintain .learnings/ for this project:
| Learning type | Promote to |
|---|---|
| Arc / Circle env gotchas | CLAUDE.md, TOOLS.md |
| Two-step payment for agents | AGENTS.md |
| Product pitch / protocol wording | README.md, demo script |
GET /api/health returns expected chainId and valid recipient.env not in git; .env.example updated for new varsnpm run build passes_meta.json