Create Auth Intent

Create a wallet authentication challenge
View as Markdown

Create an auth intent

1import { Gwop } from "@gwop/sdk";
2
3const gwop = new Gwop({
4 merchantApiKey: process.env.GWOP_MERCHANT_API_KEY,
5});
6
7const { result: intent } = await gwop.authIntents.create({
8 idempotencyKey: crypto.randomUUID(),
9});
10
11// Hand these to the agent
12intent.challenge.paymentMethods.forEach((pm) => {
13 console.log(pm.chain, pm.paymentUrl);
14});

Response

1{
2 "authIntentId": "ai_mn5e49p01TJe5YUJ-Cw",
3 "status": "OPEN",
4 "expiresAt": "2026-03-25T02:04:08.841Z",
5 "challenge": {
6 "amountUsdcAtomic": "1000",
7 "paymentMethods": [
8 {
9 "id": "x402-base",
10 "chain": "base",
11 "paymentUrl": "https://agents.gwop.io/v1/invoices/inv_.../x402/base"
12 },
13 {
14 "id": "x402-solana",
15 "chain": "solana",
16 "paymentUrl": "https://agents.gwop.io/v1/invoices/inv_.../x402/solana"
17 }
18 ]
19 }
20}

Parameters

The body is optional. You can create an auth intent with no parameters:

1const { result } = await gwop.authIntents.create({
2 idempotencyKey: crypto.randomUUID(),
3});

Or pass optional hints:

FieldTypeRequiredDescription
knownWalletHintstringNoPrevious wallet identity ({chain}:{address}) for session continuity
metadataobjectNoArbitrary metadata stored with the auth intent
1const { result } = await gwop.authIntents.create({
2 idempotencyKey: crypto.randomUUID(),
3 body: {
4 knownWalletHint: "base:0x742d35Cc6634C0532925a3b844Bc9e7595f5bA16",
5 metadata: { source: "mobile-app" },
6 },
7});

Challenge details

FieldDescription
amountUsdcAtomicDust amount as a string ("1000" = $0.001 USDC)
paymentMethods[].idMethod identifier (x402-base, x402-solana)
paymentMethods[].chainChain name (base, solana)
paymentMethods[].paymentUrlx402 endpoint the agent POSTs to

The challenge amount is fixed at $0.001 USDC — just enough to prove wallet ownership.

Idempotency

Auth intents have strict idempotency. Reusing an idempotencyKey returns IDEMPOTENCY_CONFLICT (409) rather than the original response. Always generate a fresh key for each new auth intent.

This is different from invoice creation, where the same key returns the original response.

Expiry

Auth intents expire after 10 minutes. If the agent doesn’t pay the challenge within that window, create a new intent.

Next step