SDK Reference

Complete method reference for @gwop/sdk

Package: @gwop/sdk

Invoices

`gwop.invoices.create(request)`

Create an invoice for agent payment.

1 const { result } = await gwop.invoices.create({
2   idempotencyKey: crypto.randomUUID(),
3   body: {
4     amountUsdc: 5_000_000,       // Required — atomic units (6 decimals)
5     description: "Starter plan",  // Optional
6     metadata: { orderId: "123" }, // Optional — arbitrary key-value pairs
7     metadataPublic: false,        // Optional — expose metadata in public invoice view
8     expiresInSeconds: 900,        // Optional — TTL (default 900 = 15 min)
9   },
10 });

Returns: id, publicInvoiceId, merchantId, amountUsdc, currency, status, agentProtocol, createdAt, expiresAt

The create response is the source of truth for the payable total. If Gwop applies fees or other pricing adjustments, the returned amountUsdc can differ from the base amount you submitted. Use the public invoice pricing block when you need to show a breakdown.

`gwop.invoices.list(request?)`

List invoices with pagination and optional status filter.

1 const { result } = await gwop.invoices.list({
2   limit: 20,       // Optional — default 20
3   offset: 0,       // Optional — default 0
4   status: "PAID",  // Optional — "OPEN", "PAYING", "PAID", "EXPIRED", "CANCELED"
5 });
6 
7 result.invoices;          // Array<InvoiceListItem>
8 result.pagination.total;  // Total matching invoices
9 result.pagination.hasMore;

`gwop.invoices.get(request)`

Get the full public invoice view. Takes publicInvoiceId (inv_*).

1 const { result } = await gwop.invoices.get({
2   id: "inv_7dbeeaad8ebf4f5298c380c90e4b3576",
3 });

Returns: Full checkout view including amount, pricing (baseAmount, gwopFee, total), merchant, paymentMethods (when OPEN), statusCheck, links, and settlement fields (when PAID).

`gwop.invoices.cancel(request)`

Cancel an open invoice. Takes merchant UUID id.

1 const { result } = await gwop.invoices.cancel({
2   id: "ba7bc94a-5468-42f4-9f04-2502e50c7501",
3 });
4 
5 result.status;     // "CANCELED"
6 result.canceledAt; // ISO 8601

Canceling an already-canceled invoice is idempotent (returns the same response). Canceling a non-OPEN invoice throws INVOICE_CANCEL_NOT_ALLOWED.

Auth Intents

`gwop.authIntents.create(request)`

Create a wallet authentication challenge. The agent pays a dust amount ($0.001 USDC) to prove wallet ownership.

1 const { result } = await gwop.authIntents.create({
2   idempotencyKey: crypto.randomUUID(),
3   body: {
4     knownWalletHint: "0x742d...", // Optional — pre-fill wallet
5     metadata: { source: "api" },  // Optional
6   },
7 });
8 
9 result.authIntentId;                  // UUID
10 result.challenge.amountUsdcAtomic;    // "1000" ($0.001)
11 result.challenge.paymentMethods;      // Array of payment options

Auth intents enforce strict idempotency — reusing an idempotencyKey returns 409 IDEMPOTENCY_CONFLICT, not the original response. Always use a fresh UUID.

`gwop.authIntents.exchange(request)`

Exchange a settled auth intent for a JWT.

1 const { result } = await gwop.authIntents.exchange({
2   authIntentId: intent.authIntentId,
3   idempotencyKey: crypto.randomUUID(),
4 });
5 
6 result.accessToken;          // RS256-signed JWT
7 result.principal.sub;        // "base:0x742d..." or "solana:7sSi..."
8 result.account.isNewAccount; // true on first auth

Throws AUTH_INTENT_NOT_SETTLED (402) if the agent hasn’t paid yet. Throws AUTH_INTENT_NOT_FOUND (404) for invalid intent IDs.

Auth Sessions

`gwop.authSessions.get(request)`

1 const { result } = await gwop.authSessions.get({
2   sessionId: "sess_...",
3 });
4 
5 result.status;        // "active", "revoked", or "expired"
6 result.walletAddress;
7 result.chain;
8 result.expiresAt;

`gwop.authSessions.revoke(request)`

1 await gwop.authSessions.revoke({
2   sessionId: "sess_...",
3 });

JWKS

`gwop.auth.getJwks()`

Fetch the JSON Web Key Set for local JWT verification.

1 const { result } = await gwop.auth.getJwks();
2 // result.keys — Array of JWK objects (RS256)

Use with jose:

1 import * as jose from "jose";
2 
3 const { result: jwksResponse } = await gwop.auth.getJwks();
4 const jwks = jose.createLocalJWKSet({ keys: jwksResponse.keys });
5 
6 const { payload } = await jose.jwtVerify(token, jwks, {
7   issuer: "https://identity.gwop.io",
8   algorithms: ["RS256"],
9 });

Webhooks

`gwop.validateWebhook(options)`

Verify HMAC-SHA256 signature, check timestamp freshness (300s tolerance), and parse into a typed event.

1 const gwop = new Gwop({
2   merchantApiKey: process.env.GWOP_MERCHANT_API_KEY,
3   webhookSecret: process.env.GWOP_WEBHOOK_SECRET,
4 });
5 
6 const event = await gwop.validateWebhook({
7   request: {
8     body: rawBody,
9     headers: {
10       "x-gwop-signature": signatureHeader,
11       "x-gwop-event-id": eventId,
12       "x-gwop-event-type": eventType,
13       "content-type": "application/json",
14     },
15     url: "https://your-app.com/webhooks/gwop",
16     method: "POST",
17   },
18 });
19 
20 event.body.eventType;  // "invoice.paid" | "invoice.expired" | "invoice.canceled"
21 event.body.eventId;    // UUID for deduplication
22 event.body.data;       // Typed event data

Requires webhookSecret in the constructor. Uses Web Crypto API — works in Node.js, Deno, Bun, and edge runtimes.

1	const { result } = await gwop.invoices.create({
2	idempotencyKey: crypto.randomUUID(),
3	body: {
4	amountUsdc: 5_000_000, // Required — atomic units (6 decimals)
5	description: "Starter plan", // Optional
6	metadata: { orderId: "123" }, // Optional — arbitrary key-value pairs
7	metadataPublic: false, // Optional — expose metadata in public invoice view
8	expiresInSeconds: 900, // Optional — TTL (default 900 = 15 min)
9	},
10	});

1	const { result } = await gwop.invoices.list({
2	limit: 20, // Optional — default 20
3	offset: 0, // Optional — default 0
4	status: "PAID", // Optional — "OPEN", "PAYING", "PAID", "EXPIRED", "CANCELED"
5	});
6
7	result.invoices; // Array<InvoiceListItem>
8	result.pagination.total; // Total matching invoices
9	result.pagination.hasMore;

1	const { result } = await gwop.invoices.get({
2	id: "inv_7dbeeaad8ebf4f5298c380c90e4b3576",
3	});

1	const { result } = await gwop.invoices.cancel({
2	id: "ba7bc94a-5468-42f4-9f04-2502e50c7501",
3	});
4
5	result.status; // "CANCELED"
6	result.canceledAt; // ISO 8601

1	const { result } = await gwop.authIntents.create({
2	idempotencyKey: crypto.randomUUID(),
3	body: {
4	knownWalletHint: "0x742d...", // Optional — pre-fill wallet
5	metadata: { source: "api" }, // Optional
6	},
7	});
8
9	result.authIntentId; // UUID
10	result.challenge.amountUsdcAtomic; // "1000" ($0.001)
11	result.challenge.paymentMethods; // Array of payment options

1	const { result } = await gwop.authIntents.exchange({
2	authIntentId: intent.authIntentId,
3	idempotencyKey: crypto.randomUUID(),
4	});
5
6	result.accessToken; // RS256-signed JWT
7	result.principal.sub; // "base:0x742d..." or "solana:7sSi..."
8	result.account.isNewAccount; // true on first auth

1	const { result } = await gwop.authSessions.get({
2	sessionId: "sess_...",
3	});
4
5	result.status; // "active", "revoked", or "expired"
6	result.walletAddress;
7	result.chain;
8	result.expiresAt;

1	await gwop.authSessions.revoke({
2	sessionId: "sess_...",
3	});

1	const { result } = await gwop.auth.getJwks();
2	// result.keys — Array of JWK objects (RS256)

1	import * as jose from "jose";
2
3	const { result: jwksResponse } = await gwop.auth.getJwks();
4	const jwks = jose.createLocalJWKSet({ keys: jwksResponse.keys });
5
6	const { payload } = await jose.jwtVerify(token, jwks, {
7	issuer: "https://identity.gwop.io",
8	algorithms: ["RS256"],
9	});

1	const gwop = new Gwop({
2	merchantApiKey: process.env.GWOP_MERCHANT_API_KEY,
3	webhookSecret: process.env.GWOP_WEBHOOK_SECRET,
4	});
5
6	const event = await gwop.validateWebhook({
7	request: {
8	body: rawBody,
9	headers: {
10	"x-gwop-signature": signatureHeader,
11	"x-gwop-event-id": eventId,
12	"x-gwop-event-type": eventType,
13	"content-type": "application/json",
14	},
15	url: "https://your-app.com/webhooks/gwop",
16	method: "POST",
17	},
18	});
19
20	event.body.eventType; // "invoice.paid" \| "invoice.expired" \| "invoice.canceled"
21	event.body.eventId; // UUID for deduplication
22	event.body.data; // Typed event data