# usevig

> Agentic stablecoin payments for people and software.
> The active product is the CREATE2 checkout flow at POST /v1/checkouts.
> usevig holds no funds, keys, or gas money.

## The payment model

1. The merchant provides an EVM payout_address that the merchant controls.
2. POST /v1/checkouts creates a unique address for each checkout, chain, and token.
3. The payer sends an ordinary ERC-20 transfer to the selected address.
4. usevig watches the chain and sends signed webhooks as finality advances.
5. The merchant requests an unsigned collection transaction, signs it, and pays collection gas.

The checkout address has no private key. Its code fixes the only possible payout
destination. usevig cannot redirect, freeze, or spend the funds.

Gas responsibilities are explicit:
- The payer pays gas for the original stablecoin transfer.
- The merchant pays collection gas.
- usevig pays no transaction gas and holds no gas money.

usevig charges per verified transaction. It never takes a percentage of payment value.

## Start free on Base Sepolia

1. Create a test merchant. No signup or payment is required.

   curl -X POST https://usevig.com/v1/merchants \
     -H 'Content-Type: application/json' \
     -d '{"network":"base-sepolia","payout_address":"0xYourAddress"}'

   Save api_key and webhook_secret. Each appears once.

2. Create a $0.01 checkout.

   curl -X POST https://usevig.com/v1/checkouts \
     -H "Authorization: Bearer $VIG_KEY" \
     -H 'Content-Type: application/json' \
     -d '{"amount_usd":0.01,"accept":[{"network":"base-sepolia","token":"USDC"}]}'

   The response contains checkout_url and options. Each option contains network,
   token, decimals, exact amount, and a unique receiving address.

3. Give checkout_url to a person, or give one option to a program.

4. Fulfil only after a checkout.paid webhook or an authenticated status read.

The public demo at https://usevig.com/pay/demo creates this same checkout type and
redirects to /pay/c/chk_....

## Human checkout

GET /pay/c/:checkout_id is public. It shows the amount, network, receiving
address, QR code, and copy controls. The QR represents the current direct-payment
checkout. The payer makes an ordinary transfer.

## Finality and webhooks

A checkout can use instant, confirmed, safe, or finalized finality. confirmed is
the default. safe and finalized use the chain's own block tags.

Webhook types include:

  checkout.instant     checkout.confirmed    checkout.safe
  checkout.finalized   checkout.paid         checkout.underpaid
  checkout.expired     checkout.reorged

Verify X-Vig-Signature over <timestamp>.<raw body>. Deduplicate with
X-Vig-Event-Id. Fulfil on type === "checkout.paid", not on data.status.

## Collection

Paid funds wait at per-checkout addresses. Request an unsigned transaction:

   curl -H "Authorization: Bearer $VIG_KEY" \
     "https://usevig.com/v1/collect/quote?network=base"

The merchant signs and broadcasts the returned transaction. Several paid
checkout addresses can be included in one transaction, so the merchant signs
once. This is a signature convenience, not a gas optimization.

GET /v1/balance lists funds that are paid but not yet collected. Collection
remains available after a plan expires.

## Mainnet signup

Mainnet needs a paid plan. Signup is self-serve and asks for a plan and a
payout_address. It needs no KYC, email, captcha, or manual approval.

   curl -X POST https://usevig.com/v1/signup \
     -H 'Content-Type: application/json' \
     -d '{"plan":"starter","payout_address":"0xYourAddress"}'

Pay the returned checkout with an ordinary stablecoin transfer. Then poll the
returned status_url. The api_key appears once after the plan payment clears.

Plans run 30 days and have a 3-day grace period.
Renew with POST /v1/plan/renew. Coupon codes can be supplied during signup or
redeemed later with POST /v1/redeem.

Plans:
- test — $0, Base Sepolia, 10,000 verified test transactions.
- trial — $1/30 days, up to 240 verified mainnet transactions.
- starter — $49/30 days, up to 11,000 verified mainnet transactions.
- scale — $299/30 days, up to 72,000 verified mainnet transactions.

## Account settings

GET /v1/me returns account settings and usage. PATCH /v1/me changes accepted
chains and tokens, payout_address, webhook_url, finality, or name. Updates are
partial. A payout address change affects new checkouts only.

## Endpoints

POST   /v1/signup                     buy a mainnet plan through a checkout
GET    /v1/signup/:purchase_id        poll signup; returns api_key once paid
GET    /v1/plan                       current plan and expiry
POST   /v1/plan/renew                 renew or change a plan
POST   /v1/redeem                     redeem a coupon code
POST   /v1/merchants                  create a free Base Sepolia merchant
GET    /v1/config                     current network and token registry
GET    /v1/me                         account settings and usage
PATCH  /v1/me                         update account settings
POST   /v1/checkouts                  create a CREATE2 checkout
GET    /v1/checkouts/:id              read checkout status and payments
GET    /v1/checkouts                  list checkouts
GET    /pay/c/:checkout_id            current hosted checkout page
GET    /v1/collect/quote              unsigned merchant collection transaction
GET    /v1/balance                    uncollected funds
POST   /mcp                           MCP JSON-RPC endpoint
GET    /health                        liveness
GET    /openapi.json                  machine-readable API

## Supported networks and tokens

ethereum      chain 1      USDC USDT DAI PYUSD
base          chain 8453   USDC USDT DAI
arbitrum      chain 42161  USDC USDT DAI
optimism      chain 10     USDC USDT DAI
polygon       chain 137    USDC USDT DAI
base-sepolia  chain 84532  USDC TUSD

Read token addresses and decimals from GET /v1/config. DAI uses 18 decimals.
Other configured stablecoins use 6 decimals today.

## Errors

Every 4xx response has an error code and a plain-language fix. Surface the fix
without changing its meaning.

## Contact

founders@usevig.com