URLGate Logo

URLGate API

x402 Payment Protocol · Base Network · USDC

Overview

Base URL: https://urlgate.xyz

Protocol: x402 (HTTP 402 Payment Required)

Network: Base (Ethereum L2, Chain ID: 8453)

Currency: Native USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)

💡 What is x402? x402 is a web payment standard that uses HTTP 402 (Payment Required) status codes. When you request a paid resource, the server returns payment instructions. After paying on-chain, you retry with proof (transaction hash) and get access.

Authentication

Most endpoints are permissionless and use x402 payment proofs for authentication.

Payment Authentication

When an endpoint requires payment, it returns 402 Payment Required:

{
  "error": "Payment Required",
  "message": "Payment required to access this resource",
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "payTo": "0x...",
    "maxAmountRequired": "1000000",
    "resource": "/api/urlgate/create"
  }]
}

After paying on-chain, retry with:

Authorization: x402 <transaction-hash>

Link Creation

POST /api/urlgate/create $1.00 USDC

Create a new short link (for humans via web UI).

Request Body

Field Type Required Description
url string Yes Valid HTTP/HTTPS destination URL
price string Yes Access price in USDC (0.01 to 1,000,000)
wallet string Yes Your Base wallet address (receives payments)
shortcode string No Custom shortcode (3-20 chars, auto-generated if omitted)

Success Response (200)

{
  "success": true,
  "shortcode": "abc123",
  "shortUrl": "https://urlgate.xyz/abc123",
  "destinationUrl": "https://example.com/content",
  "price": "0.050000",
  "creatorWallet": "0xYourWalletAddress",
  "feeBreakdown": {
    "serviceFee": "0.000000",
    "serviceFeePercentage": 0,
    "creatorReceives": "0.050000",
    "creatorPercentage": 100
  },
  "createdAt": "2026-08-05T00:00:00.000Z"
}

Error Responses

400 Invalid URL, price, or wallet
402 Payment required ($1.00 USDC)
409 Shortcode already taken
429 Rate limited (>100/min)
POST /api/urlgate/agent/create $1.00 USDC

Create a new short link (for AI agents and programmatic access).

Same request/response as /api/urlgate/create, plus agentCreated: true in response.

Link Access

GET /api/urlgate/:code

Access a paid link. Also works as /:code (both paths identical).

Request Headers

Authorization: x402 <transaction-hash>  // After payment
X-Wallet-Address: 0xYourWallet  // Optional, check if already paid

Response (402 if unpaid)

{
  "error": "Payment Required",
  "accepts": [{
    "maxAmountRequired": "50000",  // 0.05 USDC in micro-units
    "payTo": "0xCreatorWallet"
  }]
}

Response (303 if paid)

HTTP/1.1 303 See Other
Location: https://example.com/content

Response (200 with Accept: application/json, already paid)

{
  "destination": "https://example.com/content",
  "alreadyPaid": true
}
GET /api/urlgate/:code/info

Get public information about a link without paying.

Response (200)

{
  "shortcode": "abc123",
  "destinationUrl": "https://example.com/content",
  "price": "0.050000",
  "totalClicks": 42,
  "active": true,
  "createdAt": "2026-08-05T00:00:00.000Z"
}

Payment History & Profile

GET /api/urlgate/history/:wallet

Get all links a wallet has paid to access.

Query Parameters

Parameter Type Default Description
limit number 10 Results per page (max 100)
offset number 0 Pagination offset
search string - Filter by destination URL
GET /api/urlgate/profile/:wallet

Get statistics and links created by a wallet.

Response (200)

{
  "success": true,
  "wallet": "0xCreatorWallet",
  "totalLinks": 5,
  "totalClicks": 123,
  "totalPayments": 42,
  "totalEarnings": "2.100000",
  "links": [...]
}

Code Examples

JavaScript (Browser)

// Create a link with payment
async function createPaidLink(url, price, wallet) {
  const response = await fetch('https://urlgate.xyz/api/urlgate/create', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ url, price, wallet })
  });

  if (response.status === 402) {
    const payment = await response.json();
    const payTo = payment.accepts[0].payTo;
    const amount = payment.accepts[0].maxAmountRequired;

    // Send USDC payment via MetaMask
    const txHash = await sendUSDCPayment(payTo, amount);

    // Retry with proof
    const retryResponse = await fetch('https://urlgate.xyz/api/urlgate/create', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `x402 ${txHash}`
      },
      body: JSON.stringify({ url, price, wallet })
    });

    return await retryResponse.json();
  }

  return await response.json();
}

Python

import requests

def get_link_info(shortcode):
    response = requests.get(
        f'https://urlgate.xyz/api/urlgate/{shortcode}/info'
    )
    return response.json()

def create_link(url, price, wallet, tx_hash=None):
    headers = {'Content-Type': 'application/json'}
    if tx_hash:
        headers['Authorization'] = f'x402 {tx_hash}'

    response = requests.post(
        'https://urlgate.xyz/api/urlgate/create',
        json={'url': url, 'price': price, 'wallet': wallet},
        headers=headers
    )

    if response.status_code == 402:
        payment_info = response.json()
        print(f"Payment required: {payment_info['accepts'][0]}")
        return None

    return response.json()

cURL

# Get link info
curl https://urlgate.xyz/api/urlgate/abc123/info

# Create link (returns 402 payment required)
curl -X POST https://urlgate.xyz/api/urlgate/create \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","price":"0.05","wallet":"0x..."}'

# Create link (with payment proof)
curl -X POST https://urlgate.xyz/api/urlgate/create \
  -H "Content-Type: application/json" \
  -H "Authorization: x402 0xTransactionHash..." \
  -d '{"url":"https://example.com","price":"0.05","wallet":"0x..."}'

Rate Limits

Creation endpoints: 100 requests per minute per IP

Other endpoints: No limit

Rate limit response: 429 Too Many Requests

Support

↑