For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Apply for AccessDashboard
Guides
Guides
  • Get Started
    • Introduction
    • Quickstart
  • Agent Identity
    • Overview
    • Create Auth Intent
    • Exchange for JWT
    • Sessions
    • JWKS
  • Agent Checkout
    • Overview
    • Create an Invoice
    • List Invoices
    • Get Invoice
    • Cancel Invoice
  • Integration Patterns
    • Overview
    • Shared SDK Client
    • Wallet Auth
    • JWT Verification
    • Subscription Checkout
    • Webhook Verification
  • Concepts
    • Two Invoice IDs
    • Wallet Identity
    • Session vs Token
    • Webhook-Driven State
  • Webhooks
    • Overview
    • Verify Signatures
  • Reliability
    • Errors
    • SDK Reference
Apply for AccessDashboard
On this page
  • Create an auth intent
  • Response
  • Parameters
  • Challenge details
  • Idempotency
  • Expiry
  • Next step
Agent Identity

Create Auth Intent

Create a wallet authentication challenge
||View as Markdown|
Was this page helpful?
Edit this page
Previous

Agent Auth Overview

Next

Exchange Auth Intent

Built with

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

Exchange for JWT

After the agent pays, exchange the settled intent for an access token

Auth Overview

Full auth flow, wallet identity, and what auth unlocks