Pay a Coinbase Payment Link with Stellar, Solana, BNB Chain, Bitcoin and more

What this is

A Coinbase Payment Link only accepts USDC on Base. This skill lets the caller pay one with something else:

Native SOL, native BNB, native ETH and on-chain BTC are not supported — always say "USDT on Solana", never "SOL".

How it works: the router quotes the Coinbase link, creates a one-time bridge order with a deposit address for the coin you chose, and once your deposit lands, a funder wallet pays the Coinbase invoice. There is no discount — callerPays equals the invoice amount. If a response ever shows a discount, or callerPays differs from the invoice, stop and explain; do not proceed.

Bitrefill invoice

Supported targets are Coinbase payment links and Bitrefill invoices. Stripe checkout is not supported by this skill.

1. The user (or their agent, via Bitrefill's site or MCP) creates a Bitrefill invoice and chooses USDC on Base as the payment method. Bitrefill shows an invoice id, a Base receiving address (0x…), an exact USDC amount and an expiry.

2. Run, with the coin the user actually holds:

   npx @rozoai/checkout pay --bitrefill-invoice <id> --to <0x…> --amount <USDC> \
     --expires-at <ISO> --with usdc-stellar      # or --from stellar-usdc, usdt-solana, …
   

   There is no quote step: mpprouter creates a Rozo exactOut order delivering exactly that USDC amount to the Bitrefill address (the skill never writes to payment-api directly). The deposit you send is that amount plus bridge fees.

3. Rails, all hard aborts: the address must be a 0x EVM address, the amount a positive USDC decimal (≤ 6 dp), --expires-at is required (the invoice expiry, ≤ 30 min out); at least 5 minutes must remain to create an order and 2 minutes to show the deposit or send (the invoice expiry is the only clock used), and neither the Bitrefill address nor the deposit address may be on the compromised-address list. The router's response and the live order must echo the same invoice id, address and amount (BITREFILL_ECHO_MISMATCH otherwise) before any deposit is shown or any send happens. Re-running for the same invoice resumes its order (router DUPLICATE_INVOICE).

4. Same binding confirmation and --send rules as a Coinbase link. Status: rozo-checkout status <rozoPaymentId> reports settled once the Rozo payout to the Bitrefill address completes (payment_payout_completed, or payment_completed with a payout tx hash); there is no Coinbase stage. Works without a local record (provider read from the order).

Router errors to relay as-is: BITREFILL_DISABLED, INVALID_ADDRESS, INVALID_AMOUNT, AMOUNT_OUT_OF_RANGE, INVOICE_EXPIRING, BLOCKED_ADDRESS, UNSUPPORTED_SOURCE, INVALID_INPUT (400), and BITREFILL_NOT_CONFIGURED / RETRY_LATER (503: nothing was created, retry later).

OpenRouter top-up — when there is no link yet

OpenRouter has no public API for creating crypto credit checkouts (the old POST /api/v1/credits/coinbase returns HTTP 410 Gone). The link can only be created inside the user's own logged-in OpenRouter session. Two ways to get it:

Default — the user creates it (works everywhere)

Give these steps and wait for the URL:

1. Open https://openrouter.ai/settings/credits
2. Enable "Use crypto".
3. Enter the credit amount and click "Purchase".
4. Copy the resulting payments.coinbase.com/payment-sessions/paymentSession_*
   URL and paste it here.

Then continue with the normal flow at Step 1 (quote).

Accelerator — only when browser control already exists

If, and only if, this session already has a working browser-control capability and that browser is already signed in to OpenRouter, you may offer to click through yourself. Never tell the user to install a browser, an extension, or a plugin to unlock this — when the capability is absent, give the default steps immediately and say nothing about automation.

Ask first, in words that separate invoice creation from payment:

I can open your logged-in OpenRouter Credits page and generate the $N invoice there — that creates an unpaid checkout and moves no money. Continue?

On yes: navigate to https://openrouter.ai/settings/credits, enable Use crypto, enter the amount, click Purchase, and capture the resulting paymentSession_* URL. Targeted actions only — no screenshots and no full-page DOM dumps. On a CAPTCHA, a login wall, or an unexpected page layout, stop the automation immediately and fall back to the default steps; do not wait for the user to log in and then resume driving the browser — the accelerator only ever operates on a session that was authenticated before it started.

Verify before offering payment

Whichever path produced the URL, run Step 1 (quote) on it and fail closed unless all of these hold: the merchant is exactly OpenRouter, Inc; the status is payable; the invoice total is consistent with the requested credit amount after OpenRouter's ~5% crypto fee — accept when credit ≤ invoice ≤ credit × 1.10 (e.g. a $5.00 credit yields a $5.25 invoice; $1.00 yields $1.05), and stop and show both numbers when the invoice is below the credit or more than 10% above it; and the checkout is unexpired.

Do not enforce a minimum amount yourself — a $1.00 credit checkout has been created successfully in practice. Pass the user's amount through and surface OpenRouter's own validation error if one appears.

Consent to create the invoice is never consent to pay it. Payment continues at Step 2 of the normal flow with its own confirmation thresholds, unchanged.

Runtime

Run every command from the repository root (the directory containing SKILL.md, scripts/, package.json). If the harness sets ${CLAUDE_PLUGIN_ROOT}, use that.

cd "$SKILL_ROOT"
node scripts/dist/quote.js --url "<coinbase link>"

Each script prints one JSON object on stdout. Exit codes:

success keeps its historical meaning: the script produced a clean answer. It is not "the invoice is paid". status.js and receipt.js also return schemaVersion, paymentOutcome and nextAction; read those. receipt.js uses its own exit codes, listed in Step 6.

The bundles in scripts/dist/ are self-contained; npm install is only needed to rebuild them (npm run build).

Environment variables

Mode A — the default path — needs no key, no environment variable and no configuration at all. The variables below exist only for Mode B (--send), where this machine signs on the user's behalf. Never ask a user to set one unless they have explicitly asked for Mode B.

The recommended way to have an agent send the deposit is not to configure hot-wallet keys here. In order of preference: first, the default keyless path — the user pays from their own wallet. Second, for Stellar sources, the separate stellar-agent-wallet skill (ClawHub: shawnmuggle/stellar-agentic-wallet) pays the deposit address and memo via its send-raw command, with its own file-based key handling and confirmation prompts — no ROZO_CHECKOUT_* variable is involved. Only for unattended EVM/Solana automation does Mode B apply, and then with a dedicated hot wallet holding a low balance.

Mode B takes its signing key from the first of these that exists: --keyfile <path>; then ~/.config/solana/id.json for Solana or ROZO_CHECKOUT_EVM_KEYSTORE for EVM; then a raw key in the environment. The environment variables below may also be set in a .env — either in the working directory or at ~/.rozo-checkout/.env, whichever is found first, or an explicit --env-file <path>. Only ROZO_CHECKOUT_* keys are read from it, and the real environment wins over the file. Note that the working directory is the skill's own directory whenever you follow the run commands above, so ~/.rozo-checkout/.env is the right place for a user's own settings. A generic ~/.env is deliberately NOT read: it belongs to the user and usually holds unrelated credentials. If theirs lives elsewhere, pass --env-file <path> rather than asking them to move it.

Anonymous attribution. Every order carries attribution.install_id, a random UUID v4 created on first run and stored in ~/.rozo-checkout/prefs.json (0600), so repeat orders from one install count as one payer. When OPENROUTER_API_KEY is in the environment, attribution.account_hash (lowercase hex sha256 of "rozo-acct-v1:" + the key) is added; the raw key is never sent, logged or stored, and an OpenRouter account id is never hashed (too guessable). Neither field identifies the user or grants anything. To reset the id, delete ~/.rozo-checkout/prefs.json; to opt out, set ROZO_CHECKOUT_ANON_ID=off.

Keys are read from the environment only. Never pass a key as a command-line argument, never print one, never write one into a file, a prompt or a commit message. If the shell does not already export the key, ask the user to export it themselves — do not go hunting through .env files. The send scripts refuse to run if a .env in the working directory is tracked by git.

Confirmation thresholds

Read the USD amount from the invoice (invoice.amount).

The binding confirmation happens at step 4 (final confirm), never before — the pre-create preview cannot bind because the deposit address, the exact deposit amount and the order expiry do not exist yet.

This is enforced in code, not just documented. create-order.js withholds the full deposit address, memo and BOLT11 until it is re-run with --confirm, and --confirm writes a confirmation record bound to a digest of those exact instructions. The send scripts refuse to run without both --send and a confirmation record whose digest still matches the live deposit data.

The flow

Step 1 — quote (read-only, costs nothing)

node scripts/dist/quote.js --url "https://payments.coinbase.com/payment-links/pl_01..."

Reports merchant, invoice amount, callerPays, the Coinbase expiry and the supported source list. Exit 1 with LINK_NO_LONGER_PAYABLE means the link is used or expired — ask the merchant for a fresh one and stop.

The quoteReceipt in the output lives about 60 seconds. Do not save it; create-order.js takes its own fresh quote.

Step 2 — choose the source and preview

Ask the caller which coin and chain they want to pay with, or use what they already told you. Narrate the plan: invoice amount, merchant, chosen chain/token, callerPays (equal to the invoice — no discount). This is not the binding confirmation.

Optional contact email. If a user is present, you MAY ask once, in the same message: "Optional: an email so ROZO can reach you if the payment needs attention?" Pass it as --email <addr> in Step 3. It is never required. If the user declines, ignores the question, or no human is present (an unattended agent run), proceed without it and do not ask again. Never invent an address and never reuse one the user did not give for this purpose. An invalid address fails with INVALID_EMAIL before any order exists; fix it or drop the flag.

Step 3 — create the order

node scripts/dist/create-order.js --url "<coinbase link>" --chain 900 --token USDT
# optional contact email (Step 2):
node scripts/dist/create-order.js --url "<coinbase link>" --chain 900 --token USDT --email you@example.com

--email works the same on create-bitrefill-order.js and on rozo-checkout pay. The output reports contactEmailProvided (the address is never echoed) and a support block with ROZO's contact channels. An order that already existed for this link keeps whatever email it was created with, so contactEmailProvided is false for a reused order even when you passed --email. (On the standalone --confirm run the order is always reused, so read this field from the first run; rozo-checkout pay does that for you.)

Chain ids: 1 Ethereum · 56 BNB Chain · 137 Polygon · 8453 Base · 900 Solana · 1500 Stellar · lightning Bitcoin Lightning.

Creating an order moves no money and costs nothing if left unfunded. In one run it creates the order, verifies it against the quote, fetches the authoritative deposit instructions, runs the reuse guard, validates that the deposit instructions are complete, checks the expiry margins, checks the deposit address against the compromised-address list, and re-checks that the Coinbase link is still payable.

Without --confirm the full deposit address, memo and BOLT11 are withheld (deposit: null, depositWithheld: true). You get everything you need to ask the user — masked address, exact amount, both expiries, the reused flag — and nothing that could be paid by accident.

Any non-zero exit here means do not fund the order. See Troubleshooting.

Step 4 — final confirm (binding)

Present, from the display and expiry blocks of the run above:

About to pay:
  Merchant:   {merchant}
  Invoice:    {invoice.amount} USD   (you pay the full amount, no discount)
  Send:       {display.amount} on {display.chain}
  To:         {display.payToMasked}                <- masked, always
  Order ends: {expiry.effectiveDeadlineIso}  ({expiry.minutesOfSlack} min of slack)
  Reused existing order: {reused}

  The deposit amount can exceed the invoice: it includes the bridge and
  network fees.
  Wrong token, wrong network or wrong amount is usually unrecoverable.
  Send exactly once — a second send to this one-time address is not
  guaranteed to be credited.

Confirm? (yes/no)

Only after an explicit yes (per the threshold table), re-run the exact same command with --confirm:

node scripts/dist/create-order.js --url "<coinbase link>" --chain 900 --token USDT --confirm

That reuses the same order, re-runs every check, releases the full deposit block, and records the confirmation. Use the masked address in prose. The full address, memo and BOLT11 string live only in the machine-readable deposit object — hand that block over verbatim when the user needs to copy it, and never re-type an address by hand.

Then pick a mode.

"Mode A" and "Mode B" are internal vocabulary. Never say them to the user. They are how this document names a branch you take; they carry no meaning for someone who just wants an invoice paid. Say who sends the money and what the user has to do — nothing else about the mechanism.

Do not say	Say
"Stellar is Mode A only, no --send"	"I can't send Stellar for you — here's the address and memo to pay from your wallet" (or: "I'll pay it with your stellar-agent-wallet")
"Mode B needs ROZO_CHECKOUT_EVM_KEY"	"To have me pay it directly I'd need a hot-wallet key configured; otherwise pay from your own wallet and I'll watch for it"
"CAP_PER_TX: over the Mode B limit"	"That's over the $1,100 I'll sign for automatically — pay this one from your own wallet, which has no limit"

Whichever branch you take, the user should end up reading the same four things: the amount, the destination, the memo if there is one, and what they personally need to do next.

Mode A (default) — the user pays from their own wallet. No key, no env var, no setup. Give them the deposit block. For Lightning, deposit.lnInvoice is the BOLT11 string to scan or paste, and deposit.amount is in satoshis (deposit.isSats is true) — never call it "X BTC".

Mode B (--send, optional) — this machine pays from a hot wallet. Only when the user has asked for it. Only EVM chains and Solana — there is no --send for Stellar or Lightning; those are Mode A only. Only after the confirmation above. This is the only path that needs a key. On Solana it uses the ~/.config/solana/id.json that solana-keygen already wrote; on EVM an encrypted V3 keystore whose passphrase is prompted (never a flag). Either can be named with --keyfile. A raw key in the environment still works for unattended automation:

# EVM (Ethereum, BNB Chain, Polygon, Base)
ROZO_CHECKOUT_EVM_KEY=... node scripts/dist/send-evm.js --rozo-payment-id <uuid> --send

# Solana
ROZO_CHECKOUT_SOL_KEY=... node scripts/dist/send-sol.js --rozo-payment-id <uuid> --send

# --dry-run shows exactly what would be signed and signs nothing (no --send needed)

--send is mandatory; without it the script exits with SEND_NOT_OPTED_IN and does nothing. Mode B re-runs every check live before signing, re-proves payability as the last step before broadcast, verifies the RPC really is on the intended chain, verifies the token's on-chain decimals, signs before broadcasting so the transaction hash is known in advance, and records the send locally before broadcasting so the same order can never be paid twice. One limit: a single payment may not exceed $1,100. There is no override flag. A larger invoice is paid via Mode A, which needs no key and has no limit.

Step 5 — poll

node scripts/dist/status.js --rozo-payment-id <uuid> --watch --timeout 600

Without --timeout, --watch polls for 600 s, or for a Lightning order as long as the invoice can still be paid (at most 60 minutes). An explicit --timeout always wins.

Always pass --rozo-payment-id when you have it. A link-only query cannot reach the authoritative pay-in view (the router does not resolve the id from a link alone), so the money-detected rule cannot be enforced; the script says so via authoritativeView: false and exits non-zero rather than guessing.

States: awaiting_deposit → payin_detected → payin_confirmed → bridging → paying_coinbase → settled. Other terminal or exceptional states: expired_unfunded, underpaid, stuck_after_payment, and unknown (the backend could not be read — not evidence that nothing was paid).

expired_unfunded on a Coinbase link does not spend the link. First check the user's wallet: if anything was sent to the old deposit, or a Lightning payment is still pending, do not pay again; contact support with linkId and rozoPaymentId (the router cannot see a pending Lightning payment). If nothing was sent, re-run the same pay on the same link with the same --with: the router creates a new order for the link once it has proved every earlier order unfunded. Then follow the error code, if any:

• PAYMENT_EXPIRED with retryable: true (confirmed: false): the old order cannot be verified yet; wait a few minutes and retry.
• PAYMENT_EXPIRED with confirmed: true, or LINK_USED_OR_EXPIRED: the link cannot be paid any more; ask the merchant (OpenRouter) for a new link.
• ORDER_ALREADY_ACTIVE: a payment was found on an earlier order; do not pay again, contact support.

The extra fields are in error.details.body.

settled is only reported on real settlement evidence. The bridge reaching payment_completed is not that evidence and shows as paying_coinbase.

Alongside state, status returns paymentOutcome (one of awaiting_payment, processing, settled, expired_unfunded, needs_attention, unknown) and nextAction (type plus canRetryQuery, canCreateOrder, canSend). Only nextAction.canSend: true permits sending money. It is never true once money is detected, a send is recorded on this machine (or its record cannot be read), or the pay-in view is partial. It also requires sendWindow.ok: the same deadline-plus-margin and "link still payable" checks the send scripts run. When it is false, nextAction.reason carries the gate's code (EXPIRY_MARGIN, LINK_NO_LONGER_PAYABLE, ...).

Step 6 — report

node scripts/dist/receipt.js --rozo-payment-id <uuid>
# or: npx @rozoai/checkout receipt <uuid> --json

One read, nothing created or sent. It answers three questions separately:

Exit codes: 0 settled · 3 still in flight or unknown · 1 expired unpaid or needs a human · 2 usage.

Resuming an unpaid order. If the user created an order and did not pay (closed the session, lost the address), do NOT create a new one. Run:

node scripts/dist/resume.js <rozoPaymentId>            # masked summary + pay page
node scripts/dist/resume.js <rozoPaymentId> --confirm  # full deposit block, after the user's yes
# or: npx @rozoai/checkout resume <uuid> --json [--yes]

Read resumable and outcome. awaiting_deposit re-shows the order (same withholding and binding-confirmation rule as Step 4). paid / paid_in_progress (exit 0) means do not pay again; expired (exit 1) means follow error.message; sent_locally / needs_attention / unknown mean do not pay. resume only reads invoice-status and payments/<id>.

Report only after receipt exits 0:

✓ Paid {invoice.amount} USD to {merchant} with {token} on {chain}.
  linkId:        {linkId}
  rozoPaymentId: {rozoPaymentId}
  pay-in tx:     {payin.txHash}

The money-detected rule

Once any pay-in exists (payin.txHash, payin.confirmedAt or a non-zero amountReceived), for the rest of the conversation:

• never describe the order as a plain failure
• never advise paying again, topping up, or "trying a different chain"
• never create a new order for the same Coinbase link
• preserve linkId, rozoPaymentId and every tx hash in your reply

If the state is stuck_after_payment or underpaid, escalate for manual reconciliation with this wording:

Your payment arrived on chain but the invoice has not been settled. I am not going to retry, because retrying could take a second payment. I have kept every identifier below and this needs a human to reconcile it.

linkId: {linkId} · rozoPaymentId: {rozoPaymentId} · pay-in tx: {payin.txHash} · state: {state}

Then stop and hand off. Do not run any send script again.

x402: pay any x402 API

An x402 endpoint answers 402 Payment Required with a list of payment requirements (accepts). This skill pays it from a prepaid Rozo balance, so the agent can fund once with whatever coin it holds and then pay many small x402 calls without a wallet of its own.

# 1. Fund the balance once, with any supported coin (prints a one-time deposit address)
npx @rozoai/checkout x402 topup 20 --with usdt-solana
# 2. Call a paid endpoint: reads the 402, Rozo signs, the request is replayed with PAYMENT-SIGNATURE
npx @rozoai/checkout x402 pay https://api.example.com/v1/search --method POST --body '{"q":"..."}'
# 3. Check what is left
npx @rozoai/checkout x402 balance

Coverage, kept separate on purpose:

How x402 pay works, and what it guarantees:

1. It sends your request from this machine straight to the endpoint. Rozo never sees the request body, your headers, or the API keys you send to that service; it only sees the one accepts entry it is asked to sign.
2. On a 402 it parses the challenge (x402 v2 PAYMENT-REQUIRED header, or a v1 JSON body), keeps only exact USDC on Base, refuses anything above --max-usd (default 1.00) and any payTo on the compromised-wallet list.
3. It generates one idempotencyKey (UUID) and calls POST /v1/x402/sign. Transient failures are retried with the same key, so a timeout after Rozo already debited the balance returns the same signature instead of charging twice. The key is printed; pass it back with --idempotency-key if a run is interrupted.
4. It replays the original request with PAYMENT-SIGNATURE (v1: X-PAYMENT) and prints the response body on stdout; the payment summary and the settlement tx go to stderr (or all of it in --json).

Agent rules:

• First run x402 topup creates an agent key (ak_…), stores it in ~/.rozo-checkout/x402-key (mode 0600) and never prints it in full. That key owns the balance; do not paste it anywhere. ROZO_CHECKOUT_X402_KEY overrides the file.
• Rozo enforces per-key limits (per payment and per day). Set --max-usd to the most the user agreed to pay for this one call.
• X402_PAYER_DISABLED ("x402 payer not enabled") means the payer is off for this key right now. Nothing was charged; tell the user and stop.
• X402_PAYMENT_REJECTED or a non-2xx after paying: do not retry with a new key. Run x402 balance and report the idempotencyKey.
• X402_UNSUPPORTED: the endpoint wants something other than USDC on Base (Solana payment leg is coming later). Say so; do not try to bridge per call.
• Withdrawing a balance back to a wallet is not self-serve yet: email hi@rozo.ai with the masked key and the amount.

Raw HTTP, for agents without a shell (Bearer = the agent key): POST https://apiserver.mpprouter.dev/v1/x402/topup {amount, token, chain} and POST https://apiserver.mpprouter.dev/v1/x402/sign {accepts, budget, idempotencyKey} → the PAYMENT-SIGNATURE value. Keys: POST /v1/x402/keys; balance: GET /v1/x402/balance.

Getting help

If something goes wrong (an order is stuck, underpaid, expired after funds arrived, or the state is unknown), tell the user how to reach ROZO and give them the identifiers above:

• Email: hi@rozo.ai
• X: https://x.com/ROZOai
• Discord: https://discord.gg/EfWejgTbuU

The same channels appear in the support block of create-order output and of any status result that is not a clean answer.

Troubleshooting

Lightning invoice too short

Re-running create-order.js does not mint a fresh BOLT11: while the existing order is unexpired the router reuses it, invoice and all. The options are to wait for the order to expire and then create a new one, or to ask the merchant for a fresh Coinbase link. Do not pay a BOLT11 with under ten minutes left.

The user pasted a commerce.coinbase.com/pay/{uuid} URL

That is a different, legacy protocol. Say so and stop.

The user wants to pay in Base USDC

Not a special case. Base is a supported source like any other — chain 8453, token USDC — so run the normal flow and say nothing about modes, bridges or alternative tools. Same steps, same confirmation, same deposit block, same polling.

Do not send the user off to another skill for this. One consistent path is worth more than a theoretical shortcut, and the shortcut is not obviously cheaper anyway: a same-chain order does not bridge.

Underpaid

Report the shortfall and escalate. Do not send a top-up to the same deposit address — a second payment to a one-time address is not guaranteed to be credited.