Set Up Agentic Payments (X402)

This guide walks through adding x402 pay-per-use access to your API endpoints using Bag as the Merchant of Record.

Prerequisites

• A Bag account with KYB approved (or sandbox mode for testing)
• An API key (bag_test_sk_* for sandbox, bag_live_sk_* for production)
• A payment link with agentic proxy enabled

Step 1: Create an agentic payment link

Create a payment link and enable the agentic proxy option. This tells Bag to serve this link as an x402 resource.

curl -X POST https://getbags.app/api/payment-links \
  -H "Authorization: Bearer $BAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium API Access",
    "amount": 0.05,
    "network": "base",
    "isAgenticProxy": true,
    "targetUrl": "https://yourapi.com/v1/premium-data"
  }'

Note the payment link ID — you'll need it for the x402 endpoint URL.

Step 2: Point clients to the x402 endpoint

Your x402-protected resource is available at:

https://getbags.app/api/agent/{paymentLinkId}

When a client makes a request without payment:

curl https://getbags.app/api/agent/a1b2c3d4-e5f6-7890-abcd-ef1234567890

The server returns HTTP 402 with payment instructions in the response headers, following the x402 protocol.

Step 3: Client pays and accesses the resource

x402-compatible clients (including AI agents) automatically:

1. Read the 402 response and payment requirements
2. Send USDC payment on-chain
3. Include the payment proof in a retry request
4. Receive the protected resource

The payment is verified by the x402 facilitator (https://x402.org/facilitator), and the request is proxied to your targetUrl.

Step 4: Handle webhooks

Each x402 payment generates a payment.completed webhook with the customer identified as "X402 Agent":

{
  "event": "payment.completed",
  "data": {
    "sessionId": "...",
    "amount": 0.05,
    "network": "base",
    "customerName": "X402 Agent",
    "txHash": "0x..."
  }
}

Testing in Sandbox

1. Use a bag_test_sk_* API key
2. Create a payment link on a testnet (e.g., base_sepolia)
3. Use testnet USDC to make x402 payments
4. Verify webhooks arrive with "livemode": false

Supported HTTP Methods

The x402 agent endpoint supports all standard HTTP methods:

All methods go through the same payment verification flow.

What's next