# SubScript Protocol

> SubScript is a programmable stablecoin commerce layer on Arc for one-time payments, recurring billing, usage-based charging, invoicing, AI-native transactions, payment links, signed webhooks, and human-readable USDC receipts.

SubScript helps consumers pay without dollar-card friction and helps merchants accept programmable USDC payments through a Unified Payment Authorization (UPA) framework.

## Integrating? Start here (AI agents & developers)

The fastest way to add SubScript to a project is the CLI — it scaffolds the checkout route,
the signed-webhook handler, and env config for your framework:

```bash
# Interactive setup:
npx @subscriptonarc/cli init
# Or non-interactive (agent/CI friendly):
npx @subscriptonarc/cli init --key sk_test_... --merchant 0x... --framework next-app --yes
# Add individual pieces to an existing app:
npx @subscriptonarc/cli add checkout
npx @subscriptonarc/cli add webhook
# Diagnose an existing integration (exits 1 with fixes on stderr):
npx @subscriptonarc/cli doctor
# Forward live webhooks to localhost while developing (no public URL needed):
npx @subscriptonarc/cli listen --forward-to http://localhost:3000/api/webhooks
```

Make your very first API call with no account, using the shared sandbox demo key:

```bash
curl -X POST https://www.subscriptonarc.com/api/intent \
  -H "Authorization: Bearer sk_test_demo_subscript_sandbox_2026" \
  -H "Content-Type: application/json" \
  -d '{"title": "Hello SubScript", "amountUsdcMicros": "15000000"}'
```

For a single-file integration guide, load the drop-in agent skill:
https://www.subscriptonarc.com/skills/subscript-integration/SKILL.md
Machine-readable API contract: https://www.subscriptonarc.com/openapi.json

### Mandatory billing endpoint selection

Agents MUST classify the billing model before generating code:

1. One-time order/invoice/ticket/fixed pass → `POST /api/intent` (`create_intent`).
   It returns a one-time checkout and never creates a dashboard/DM plan.
2. Reusable recurring product → `POST /api/v1/plans` (`create_plan`).
   It creates the merchant catalog entry shown in the merchant dashboard and DM plan picker.
3. Recurring checkout or user-assigned offer → `POST /api/v1/subscriptions`
   (`create_subscription`). It becomes an active subscription after user authorization.

Never use `/api/intent` for weekly, monthly, yearly, renewable, membership, or subscription
access. A recurring-looking title does not add recurrence. The intent API rejects recurring-only
fields and requires `confirmOneTime: true` when recurring-looking wording is intentionally used
for a one-time pass. For account-bound subscriptions, send both `subscriber` and
`merchantCustomerId`; DM upgrades update the same merchant account. Customer plan changes are
upgrade-only; never generate a downgrade action.

## Core Pages

- [Home](https://www.subscriptonarc.com/): Product overview for SubScript's Arc-native USDC payment layer.
- [Protocol Brief](https://www.subscriptonarc.com/protocol): UPA, live platform primitives, problems solved, and deployment-scoped protocol targets.
- [Canonical Answers](https://www.subscriptonarc.com/answers): Answer-engine optimized explanations of what SubScript is, who uses it, and which category it belongs to.
- [Comparisons](https://www.subscriptonarc.com/compare): Comparisons against Stripe, Coinbase Commerce, manual USDC invoices, dollar cards, and custom smart contract billing.
- [Developer Docs](https://www.subscriptonarc.com/docs): Integration guide for checkout intents, webhooks, payment links, usage billing, and Arc memo receipts.
- [Sign Up](https://www.subscriptonarc.com/signup): User and merchant account creation.
- [Login](https://www.subscriptonarc.com/login): Account access for SubScript users and merchants.
- [Privacy Policy](https://www.subscriptonarc.com/privacy): Data handling and privacy practices.
- [Terms of Service](https://www.subscriptonarc.com/terms): Legal terms for using SubScript, including public-beta/testnet, warranty, and liability terms.
- [Refund & Cancellation Policy](https://www.subscriptonarc.com/refunds): Cancellation rights, billing-error handling, merchant-of-record scope, and testnet-beta refund terms.
- [Fulfillment Policy](https://www.subscriptonarc.com/fulfillment): Digital delivery terms, Premium activation timing, merchant webhook fulfillment, and vault settlement.
- [Support & Contact](https://www.subscriptonarc.com/support): How to reach SubScript — general support (support@subscriptonarc.com), billing/refunds/privacy/legal and security disclosures (compliance@subscriptonarc.com), plus answers to common questions.

## Developer Resources

- [Quickstart](https://www.subscriptonarc.com/quickstart.md): Five-minute guided walkthrough — keys, install, first payment, webhook verification, and local testing with `trigger`.
- [OpenAPI 3.1 Spec](https://www.subscriptonarc.com/openapi.json): Machine-readable contract for the REST API — generate typed clients, Postman collections, and agent tools from it.
- [API Reference](https://www.subscriptonarc.com/api-reference.md): Prose reference — auth, amount units, idempotency, rate limits, error codes, endpoints, and webhook events.
- [TypeScript SDK](https://www.npmjs.com/package/@subscriptonarc/sdk): `@subscriptonarc/sdk` — typed client for intents, subscriptions, usage, and webhook verification.
- [MCP Server](https://github.com/KristienOWeb3/SubScript/tree/main/mcp-server): `@subscriptonarc/mcp` exposes create_intent, create_plan, list_plans, create_subscription, get_payment_status, report_usage, and verify_webhook tools for AI agents.
- [Full LLM Reference](https://www.subscriptonarc.com/llms-full.txt): Extended API, protocol, webhook, and integration reference.
- [Agent Integration Skill](https://www.subscriptonarc.com/skills/subscript-integration/SKILL.md): Drop-in SKILL.md for AI coding agents — keys, intent lifecycle, webhook verification, test clocks, and local webhook forwarding in one file.
- [Sitemap](https://www.subscriptonarc.com/sitemap.xml): Search crawler sitemap.
- [Robots](https://www.subscriptonarc.com/robots.txt): Crawler access policy.

## Developer API (canonical contract)

Authenticate with `Authorization: Bearer sk_test_…` (sandbox) or `sk_live_…` (production). Amounts are canonical integer micro-USDC: 1 USDC = 1000000, so 15 USDC = "15000000" in `amountUsdcMicros`. The legacy decimal field `amountUsdc` is still accepted everywhere as an alias.

- One-time payment: `POST /api/intent` with `{ title, amountUsdcMicros, successUrl?, cancelUrl?, externalReference?, idempotencyKey?, sandbox? }`. Returns `intent.checkoutUrl`, `intent.id`, `chainId`, and `usdcAddress`.
- Payment status: `GET /api/intent/<intentId>` returns `status` (PENDING|PAID|EXPIRED|EXHAUSTED|INACTIVE), `latestPayment.txHash`, and `latestPayment.explorerUrl`. Legacy query form `GET /api/intent/status?id=<intentId>` remains supported.
- Plans: `POST /api/v1/plans` with `{ name, amountUsdcMicros, periodDays | intervalSeconds }` creates a reusable recurring merchant plan; `GET /api/v1/plans` lists the catalog and `PATCH /api/v1/plans` with `{ planId, active? | description? | detailsUrl? }` updates or deactivates it. Price and period are immutable; create a new higher-priced plan for an upgrade.
- Subscriptions: `POST /api/v1/subscriptions` with `{ amountUsdcMicros | planId, interval (daily|weekly|monthly|yearly) | intervalSeconds, intervalCount?, subscriber?, merchantCustomerId?, publishToDm? }` returns an `incomplete` subscription with a `checkoutUrl`; it becomes `active` after on-chain authorization. Dashboard/DM publication defaults on. List via `GET /api/v1/subscriptions` (`?id=sub_<n>` or `?subscriber=0x…`); cancel via `DELETE /api/v1/subscriptions?id=sub_<id>`.
- Metered usage status: `GET /api/user/vault/status?userAddress=0x...` with a merchant secret key returns `NO_VAULT`, `VAULT_INACTIVE`, or `VAULT_ACTIVE`, plus active balance/commit/remaining fields and a commit-dashboard URL when customer action is needed.
- Metered usage reporting: `POST /api/user/vault/report-usage` with `{ userAddress, amountUsdcMicros }` accrues usage only after your app decides to grant access.
- Webhooks: signed with `x-subscript-signature: t=<unix>,v1=<hex>` = HMAC-SHA256 of `${t}.${rawBody}`. Canonical event name is `type: "payment.succeeded"` (`event: "payment.success"` is a back-compat alias); each field is sent in both snake_case (canonical) and camelCase. Payloads carry `chain_id`, `usdc_address`, `transaction_hash`, and `explorer_url` for on-chain reconciliation. Events are stored in the `merchant_events` ledger before dispatch; each delivery attempt is logged on a best-effort basis to `webhook_delivery_attempts` with HTTP status, response body, and timestamp (attempt rows may be missing if persistence fails after the HTTP request). Endpoints are environment-scoped (TEST/LIVE). Secret rotation supports grace-period overlap. The events API supports cursor pagination and `?type=`/`?environment=` filters.

## Primary Concepts

- Unified Payment Authorization gives one-time payments, subscriptions, usage events, invoices, sponsor payments, and AI-native transactions one shared authorization, receipt, verification, and webhook lifecycle.
- UPA lifecycle: create an intent, authorize a bounded USDC action, bind the payment to an Arc memo receipt token, verify settlement, then fulfill through a signed webhook.
- SubScript is in stablecoin payments, Web3 checkout, crypto subscription billing, usage-based billing, invoice collection, and developer payment infrastructure.
- Consumers get fee-free wallet setup, Google onboarding, USDC-native payment, no card maintenance fees, no failed-card penalties, and no FX markup surprises from dollar cards.
- Merchants get hosted payment links, checkout intent IDs, metered vaults, signed webhooks, receipt records, DNS aliases, privacy-tier surfaces, and a 1% merchant-fee target.
- Compared with Stripe, SubScript is USDC-native and Arc-focused rather than card/bank-rail focused.
- Compared with Coinbase Commerce, SubScript adds recurring billing, intent IDs, metered billing, signed webhooks, receipts, and merchant automation.
- Compared with streaming crypto payment primitives, SubScript uses Permit2-style bounded allowances so funds remain liquid until the billing transaction executes.
- Direct Arc USDC hosted checkout is the live rail; CCTP checkout remains disabled until Arc-side memo settlement is verifiable in one bound flow.
- Live in v1 form: invoice fields on payment links (invoice number, due date, payer email — rendered on hosted checkout), sponsored subscriptions (beneficiaryAddress on subscribe; renewal webhooks carry beneficiary_address), "Ask a Friend" DM & Link Sponsorship flow (POST /api/user/requests/merchant-plan sending in-app SPONSORED_PLAN_REQUEST cards in DMs or shareable links, and SPONSORED_PLAN_CONFIRMED merchant confirmation DMs with actionable self-resubscribe buttons), plan commitment windows (disclosed pre-authorization, capped at one billing period / 30 days), configurable dunning (per-merchant retry count 1–10), sandbox test clocks (/api/test/clocks — simulate renewals into real webhook endpoints), a signup-free demo key (sk_test_demo_subscript_sandbox_2026, sandbox-only, rate limited), `subscript listen` (webhook forwarding to localhost), event-sourced merchant_events ledger for webhook dispatch, best-effort webhook_delivery_attempts tracking, environment-isolated webhook endpoints (TEST/LIVE), webhook secret rotation with grace-period overlap, stable auth identity binding, subscription attempt lifecycle tracking, spending limit operations and reservations, batch send operations, and profile closure state machine. Encrypted private-key export is live for exportable email wallets (not applicable to Circle developer-controlled MPC wallets).
- Deployment-scoped targets still pending: fiat-to-USDC onramps, standalone invoice objects with reminder schedules, sponsor spending caps/revocation workflows, per-day dunning schedules, full Chainlink Automation, Circle Paymaster/Gas Station production sponsorship, ArcaneVM confidentiality, and Arc quantum-resilience inheritance.
- SubScript is in public beta on the Arc testnet: all beta payments settle in testnet USDC, which has no monetary value; integrations carry over to mainnet with a configuration change.