Invoices

In Gwop, an invoice and a checkout are the same thing. invoices.create() opens an agent checkout — a headless payment session with x402 rails for every supported chain. The docs use both terms interchangeably: “invoice” when talking about the API primitive, “agent checkout” when talking about what the agent experiences.

You set the amount, describe what you are selling, and attach any metadata you need. Gwop generates the checkout session with x402 payment URLs for both Base and Solana. The agent fetches it, picks a chain, and pays.

This is what makes agent checkout powerful: you control the commercial terms, Gwop handles settlement. Instead of per-request micropayments tied to a single endpoint, you create an explicit commercial moment — a credit pack, a subscription, a dataset, whatever your product needs — and let the agent buy it over x402.

How it works

1. You define the product and price — your backend creates an invoice with an amount, description, and expiry. Gwop returns an inv_* identifier and generates x402 payment URLs for Base and Solana inside it.
2. You hand the invoice to the agent — pass the publicInvoiceId. The agent fetches the invoice, discovers the available payment methods, and chooses a chain.
3. The agent pays via x402 — the agent hits the x402 payment URL for their preferred chain. Gwop verifies the transaction on-chain.
4. Gwop fires a webhook — your endpoint receives invoice.paid with the transaction hash, chain, and payer wallet.
5. Your backend fulfills — grant credits, activate a plan, unlock access. The sale is complete.

Your Backend                    Gwop                          Agent
     │                           │                              │
     │── create invoice ────────>│                              │
     │<── inv_* identifier ──────│                              │
     │                           │                              │
     │── hand inv_* to agent ──────────────────────────────────>│
     │                           │                              │
     │                           │<── GET /invoices/inv_* ──────│
     │                           │── payment methods (Base/Sol) │
     │                           │                              │
     │                           │<── x402 payment ─────────────│
     │                           │── verify on-chain            │
     │                           │                              │
     │<── webhook: invoice.paid ─│                              │
     │                           │                              │
     │── fulfill ──────────────────────────────────────────────>│

After fulfillment, you have a customer with a wallet identity, a purchase record, and whatever entitlements your app granted. That is the foundation for recurring revenue — the agent can come back, authenticate with the same wallet, and pick up where it left off.

The code

1
import { Gwop } from "@gwop/sdk";
2
3
const gwop = new Gwop({
4
  merchantApiKey: process.env.GWOP_MERCHANT_API_KEY,
5
  webhookSecret: process.env.GWOP_WEBHOOK_SECRET,
6
});
7
8
// You define the product and price
9
const { result: invoice } = await gwop.invoices.create({
10
  idempotencyKey: crypto.randomUUID(),
11
  body: {
12
    amountUsdc: 5_000_000, // $5.00 USDC
13
    description: "Starter plan — 300 credits",
14
  },
15
});
16
17
// Hand the invoice ID to the agent
18
// The agent fetches it to discover payment methods for Base and Solana
19
console.log(invoice.publicInvoiceId); // inv_7dbeeaad...
20
21
// Gwop tells you when the agent paid
22
const event = await gwop.validateWebhook({ request });
23
if (event.body.eventType === "invoice.paid") {
24
  // Fulfill: grant credits, activate plan, unlock access
25
  const { publicInvoiceId, paymentChain, txHash } = event.body.data;
26
}

Invoice lifecycle

Every invoice moves through a deterministic state machine:

OPEN ──> PAYING ──> PAID
  │
  ├──> EXPIRED
  └──> CANCELED

What you can sell

Because you control the amount, description, metadata, and fulfillment logic, invoices are a general-purpose commercial primitive. You can sell anything:

• Prepaid credits — sell a credit pack, deduct on usage
• Subscriptions and plans — charge monthly, enforce tier limits
• One-time purchases — reports, datasets, API packages, premium features
• Usage-based billing — invoice for accumulated usage at intervals
• Any digital good — if you can define a price and fulfillment, you can sell it to an agent

Multichain

Every invoice contains x402 payment URLs for both Base (EVM) and Solana. When the agent fetches the invoice, it sees payment methods for both chains and chooses which to use. No configuration required on your end — Gwop generates the rails for both chains automatically.

Next steps