Invoices

A Gwop invoice is a merchant-defined payment object. You set the amount, describe what’s being sold, and attach any metadata you need. Gwop generates x402 payment URLs for both Base and Solana inside the invoice. The agent fetches the invoice, picks a chain, and pays.

This is what makes invoices 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 ──────────────────────────────────────────────>│

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