402ify API Reference

Overview

This document covers the 402ify API for creating and managing PayGates (payment-protected API endpoints). For x402-hub protocol endpoints, see x402-hub API Reference.

Base URL

Production: https://402ify.com, https://402.sigwei.com

All endpoints use /api/v1/ prefix with standardized responses including API version metadata.

Authentication

402ify uses the same authentication system as x402-hub (SIWE-based wallet signing).

Bearer Token (Required for PayGate Management)

Authorization: Bearer <JWT_TOKEN>

Authentication Flow

Get Authentication Message

GET /api/v1/auth/message?walletAddress=0xYOUR_WALLET

Response:
{
  "message": "402.sigwei.com wants you to sign in with your Ethereum account:\n0x742D35Cc6634C19D8B4e8d5C1234567890123456\n\nI accept the Sigwei Terms of Service: https://402.sigwei.com/tos\n\nURI: https://402.sigwei.com/api/v1/auth\nVersion: 1\nChain ID: 8453\nNonce: abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\nIssued At: 2024-01-15T10:30:00Z",
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

SIWE Compliance: Authentication messages follow the Sign-In with Ethereum (EIP-4361) standard with EIP-55 checksummed addresses.

POST /api/v1/auth/login
Content-Type: application/json

{
  "message": "FULL_SIGNED_MESSAGE",
  "signature": "0x1234567890abcdef..."
}

Response:
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "abcd1234...",
  "user": {
    "id": 1,
    "walletAddress": "0x742d35cc6634c0532925a3b8c2414f4e456c10f4"
  },
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Refresh Token

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "your_refresh_token"
}

Get Current User

GET /api/v1/auth/me
Authorization: Bearer <token>

Logout

POST /api/v1/auth/logout
Authorization: Bearer <token>

PayGate Management APIs

List PayGates

GET /api/v1/paygates
Authorization: Bearer <token>

Response:
{
  "data": [
    {
      "id": 1,
      "shortCode": "abc123",
      "target": "https://api.example.com/data",
      "method": "GET",
      "resourceType": "url",
      "accessUrl": "https://402ify.com/abc123",
      "price": "0.01",
      "type": "credit",
      "credits": 1,
      "network": "base-sepolia",
      "isEnabled": true,
      "requireAuth": false,
      "headerAuthMode": "hmac",
      "assumeValid": false,
      "title": "API Access",
      "description": "Premium data access",
      "attemptCount": 5,
      "paymentCount": 3,
      "accessCount": 3,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Create PayGate (URL)

POST /api/v1/paygates
Authorization: Bearer <token>
Content-Type: application/json

{
  "targetUrl": "https://api.example.com/premium-endpoint",
  "method": "GET",
  "price": "0.01",
  "network": "base-sepolia",
  "paymentAddress": "0xYOUR_PAYMENT_ADDRESS",
  "requireAuth": false,
  "headerAuthMode": "hmac",
  "assumeValid": false,
  "type": "credit",
  "credits": 1,
  "title": "Premium API Access",
  "description": "Real-time data with authentication",
  "customHeaders": {
    "X-API-Key": "your-api-key",
    "Content-Type": "application/json",
    "X-Client-ID": "sigwei-client"
  }
}

Response:
{
  "id": 1,
  "shortCode": "abc123",
  "target": "https://api.example.com/premium-endpoint",
  "method": "GET",
  "resourceType": "url",
  "accessUrl": "https://402ify.com/abc123",
  "price": "0.01",
  "requireAuth": false,
  "headerAuthMode": "hmac",
  "title": "Premium API Access",
  "description": "Real-time data with authentication",
  "customHeaders": {
    "X-API-Key": "your-api-key",
    "Content-Type": "application/json",
    "X-Client-ID": "sigwei-client"
  },
  "attemptCount": 0,
  "paymentCount": 0,
  "accessCount": 0,
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Multi-Method PayGates

PayGates can support multiple HTTP methods by providing a comma-separated string:

POST /api/v1/paygates
Authorization: Bearer <token>
Content-Type: application/json

{
  "targetUrl": "https://api.example.com/premium-endpoint",
  "method": "GET,POST,PUT",
  "price": "0.01",
  "paymentAddress": "0xYOUR_PAYMENT_ADDRESS",
  "title": "Multi-Method API Access"
}

Response:
{
  "id": 2,
  "shortCode": "def456",
  "target": "https://api.example.com/premium-endpoint",
  "method": "GET,POST,PUT",
  "resourceType": "url",
  "accessUrl": "https://402ify.com/def456",
  "price": "0.01",
  "title": "Multi-Method API Access",
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Create PayGate (File)

POST /api/v1/paygates
Authorization: Bearer <token>
Content-Type: application/json

{
  "originalFilename": "document.pdf",
  "price": "0.05",
  "network": "base-sepolia",
  "paymentAddress": "0xYOUR_PAYMENT_ADDRESS",
  "headerAuthMode": "hmac",
  "assumeValid": false,
  "title": "Premium Document",
  "description": "Exclusive research content"
}

Response:
{
  "id": 2,
  "shortCode": "def456",
  "target": "document.pdf",
  "resourceType": "file",
  "accessUrl": "https://402ify.com/def456",
  "uploadUrl": "https://r2.amazonaws.com/upload-url...",
  "price": "0.05",
  "title": "Premium Document",
  "description": "Exclusive research content",
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Get Specific PayGate

GET /api/v1/paygates/{id}
Authorization: Bearer <token>

Update PayGate

PUT /api/v1/paygates/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Updated API Access",
  "description": "Updated description",
  "price": "0.02",
  "paymentAddress": "0xNEW_PAYMENT_ADDRESS_HERE",
  "requireAuth": true,
  "headerAuthMode": "plaintext",
  "assumeValid": false,
  "method": "GET,POST",
  "credits": 5
}

Available Fields:

title: Display name for the PayGate (optional)
description: Detailed description (optional)
price: New price in USDC (e.g., "0.02" for $0.02) (optional)
paymentAddress: Blockchain address where payments should be sent (optional, important for security)
credits: Number of times a payment can be reused (optional)
requireAuth: Whether authentication is required (optional)
headerAuthMode: How to send sigwei_secret ("plaintext" or "hmac") (optional)
assumeValid: Skip blockchain verification for faster payments (optional, defaults to false)
method: HTTP methods as comma-separated string (e.g., "GET,POST,PUT") (optional)

Security Note: The paymentAddress field allows you to update where payments are sent. This is critical for security if your original payment address becomes compromised. All payment addresses are encrypted and stored securely.

Update PayGate Secret

PATCH /api/v1/paygates/{id}/secret
Authorization: Bearer <token>
Content-Type: application/json

{
  "sigweiSecret": ""  // Empty string generates new random secret
}

// Or set custom secret
{
  "sigweiSecret": "your-custom-secret"
}

Delete PayGate

DELETE /api/v1/paygates/{id}
Authorization: Bearer <token>

Transfer API

Execute USDC Transfer

POST /api/v1/transfer
Content-Type: application/json

{
  "network": "base-sepolia",
  "signature": "0x1234567890abcdef...",
  "authorization": {
    "from": "0xYOUR_WALLET",
    "to": "0xRECIPIENT_WALLET",
    "value": "1000000",  // 1 USDC in microdollars
    "validAfter": "0",
    "validBefore": "9999999999",
    "nonce": "0x1234567890abcdef..."
  }
}

Response:
{
  "success": true,
  "message": "Transfer completed successfully",
  "transaction": "0x1325a7b20147c57dab8c3f3f1234567890abcdef1234567890abcdef1234567890",
  "networkName": "base-sepolia",
  "x402Data": {
    "paymentRequirements": "{\"amount\":1000000,\"currency\":\"USDC\",\"to\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\"}",
    "paymentPayload": {
      "x402Version": 1,
      "scheme": "exact",
      "network": "base-sepolia",
      "payload": {
        "signature": "0x1234567890abcdef...",
        "authorization": {
          "from": "0xYOUR_WALLET",
          "to": "0xRECIPIENT_WALLET",
          "value": "1000000",
          "validAfter": "0",
          "validBefore": "9999999999",
          "nonce": "0x1234567890abcdef..."
        }
      }
    },
    "settleResponse": {
      "status": "success",
      "transaction": "0x1325a7b20147c57dab8c3f3f1234567890abcdef1234567890abcdef1234567890",
      "network": "base-sepolia",
      "amount": "1000000"
    },
    "typedData": "{\"types\":{\"EIP712Domain\":[]}}"
  },
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Premium PayGates API

Create Premium PayGate

POST /api/v1/premium
Authorization: Bearer <token>
Content-Type: application/json

{
  "shortCode": "your-custom-code",
  "years": 1,
  "payGateRequest": {
    "price": "1000000",
    "paymentAddress": "0x742d35Cc6634C0532925a3b8c2414F4e456C10F4",
    "targetUrl": "https://api.example.com/endpoint",
    "method": "GET",
    "title": "My Premium API",
    "description": "Custom branded API endpoint",
    "assumeValid": false
  }
}

Response:
{
  "id": "paygate-id",
  "shortCode": "your-custom-code",
  "accessUrl": "https://402ify.com/your-custom-code",
  "expiresAt": "2026-08-18T00:00:00Z",
  "isPremium": true,
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Extend Premium PayGate

PUT /api/v1/premium/{shortCode}/extend
Authorization: Bearer <token>
Content-Type: application/json

{
  "years": 2
}

Response:
{
  "shortCode": "your-custom-code",
  "expiresAt": "2028-08-18T00:00:00Z",
  "yearsAdded": 2,
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Dashboard API

Get Statistics

GET /api/v1/dashboard/stats
Authorization: Bearer <token>

Response:
{
  "testEarnings": 250000,
  "testPurchases": 15,
  "realEarnings": 1500000,
  "realPurchases": 8,
  "dailyPurchases": [
    {
      "date": "2024-01-15",
      "testPurchases": 3,
      "realPurchases": 2,
      "testEarnings": 50000,
      "realEarnings": 300000
    }
  ],
  "routeStats": {
    "totalRoutes": 12,
    "activeRoutes": 10,
    "disabledRoutes": 2,
    "totalAttempts": 145,
    "totalPayments": 87,
    "totalAccesses": 83,
    "conversionRate": 60.0,
    "accessRate": 95.4
  },
  "creditStats": {
    "totalAvailable": 500,
    "totalUsed": 234,
    "utilizationRate": 46.8
  },
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Account Management API

Get Account Tier Information

GET /api/v1/account/tier
Authorization: Bearer <token>

Response:
{
  "accountTier": "pro",
  "billingCycle": "monthly",
  "tierUpdatedAt": "2024-01-15T10:30:00Z",
  "paygateCount": 15,
  "paygateLimit": 20,
  "rateLimit": 60,
  "monthlyPriceUSDC": 20000000,
  "yearlyPriceUSDC": 200000000,
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Response Fields:

accountTier: Current account tier ("free", "pro", "max")
billingCycle: Billing frequency ("monthly", "yearly")
tierUpdatedAt: When tier was last updated (ISO 8601)
paygateCount: Current number of PayGates created
paygateLimit: Maximum PayGates allowed for this tier
rateLimit: Requests per minute per PayGate (0 = unlimited)
monthlyPriceUSDC: Monthly price in wei USDC (6 decimals)
yearlyPriceUSDC: Yearly price in wei USDC (0 if not available)

Get Billing Information

GET /api/v1/account/billing
Authorization: Bearer <token>

Response:
{
  "currentTier": "pro",
  "effectiveTier": "pro",
  "billingCycle": "monthly",
  "tierExpiresAt": "2024-02-15T10:30:00Z",
  "pendingTier": null,
  "pendingExpiresAt": null,
  "accountCreatedAt": "2024-01-01T10:00:00Z",
  "tierLastUpdated": "2024-01-15T10:30:00Z",
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Response Fields:

currentTier: Currently active tier
effectiveTier: Tier considering expiration (falls back to "free" if expired)
billingCycle: Current billing cycle ("monthly", "yearly")
tierExpiresAt: When current tier expires (null for free tier)
pendingTier: Tier scheduled to activate after current expires (null if none)
pendingExpiresAt: When pending tier will expire (null if no pending tier)
accountCreatedAt: Account creation date (ISO 8601)
tierLastUpdated: When tier was last modified (ISO 8601)

Update Account Tier

POST /api/v1/account/update
Authorization: Bearer <token>
Content-Type: application/json

{
  "targetTier": "pro",
  "billingCycle": "monthly",
  "duration": 1
}

Response:
{
  "success": true,
  "newTier": "pro",
  "message": "Tier update successful",
  "effectiveDate": "2024-01-15T10:30:00Z",
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Request Body:

targetTier (required): Target tier ("pro", "max")
billingCycle (optional): "monthly" or "yearly" (defaults to "monthly")
duration (optional): Number of billing cycles (defaults to 1)

Response Fields:

success: Whether update was successful
newTier: The tier that was set
message: Human-readable status message
effectiveDate: When the change takes effect (upgrades immediate, downgrades at expiration)

Tier Behavior:

Upgrades: Applied immediately with new expiration date
Downgrades/Extensions: Scheduled as pending, activate when current tier expires
Free to Paid: Always immediate upgrade
Paid to Free: Only when current paid tier expires

Available Tiers:

Free: 10 PayGates, 5 req/min per PayGate, $0/month
Pro: 20 PayGates, 60 req/min per PayGate, $20/month or $200/year
Max: 100 PayGates, unlimited req/min, $100/month (no yearly option)

Transaction History API

Get Transaction History

GET /api/v1/history?limit=20&offset=0&network=base-sepolia
Authorization: Bearer <token>

Query Parameters:
- limit (required): Number of transactions to return (1-100)
- offset (optional): Number of transactions to skip (default: 0)
- network (optional): Filter by network ("base-sepolia" or "base")

Response:
{
  "success": true,
  "history": [
    {
      "id": 123,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:35:00Z",
      "signerAddress": "0x742d35cc6634c0532925a3b8c2414f4e456c10f4",
      "amount": "1000000",
      "network": "base-sepolia",
      "chainId": 84532,
      "transactionHash": "0x1234567890abcdef...",
      "status": "success",
      "error": null,
      "type": "transfer",
      "x402Data": {
        "paymentRequirements": "{\"amount\":1000000,\"currency\":\"USDC\",\"to\":\"0x...\"}",
        "paymentPayload": [123, 34, 120, 52, 48, 50, 86, 101, 114, 115, 105, 111, 110, 34, 58, 49],
        "paymentHeader": "Bearer payment_token_here",
        "settleResponse": [123, 34, 115, 116, 97, 116, 117, 115, 34, 58, 34, 115, 117, 99, 99, 101, 115, 115, 34],
        "typedData": "{\"types\":{\"EIP712Domain\":[]}}"
      },
      "purchaseData": null
    },
    {
      "id": 124,
      "createdAt": "2024-01-15T11:00:00Z",
      "updatedAt": "2024-01-15T11:05:00Z",
      "signerAddress": "0x742d35cc6634c0532925a3b8c2414f4e456c10f4",
      "amount": "50000",
      "network": "base-sepolia",
      "chainId": 84532,
      "transactionHash": "0xabcdef1234567890...",
      "status": "success",
      "error": null,
      "type": "purchase",
      "x402Data": {
        "paymentRequirements": "{\"amount\":50000,\"currency\":\"USDC\",\"to\":\"0x...\"}",
        "paymentPayload": [123, 34, 120, 52, 48, 50, 86, 101, 114, 115, 105, 111, 110, 34, 58, 49],
        "paymentHeader": "Bearer payment_token_here",
        "settleResponse": [123, 34, 115, 116, 97, 116, 117, 115, 34, 58, 34, 115, 117, 99, 99, 101, 115, 115, 34],
        "typedData": "{\"types\":{\"EIP712Domain\":[]}}"
      },
      "purchaseData": {
        "shortCode": "abc123",
        "targetUrl": "https://api.example.com/data",
        "method": "GET",
        "purchaseType": "credit",
        "creditsAvailable": 5,
        "creditsUsed": 1,
        "paidRouteId": 42,
        "paidToAddress": "0x742d35cc6634c0532925a3b8c2414f4e456c10f4",
        "title": "Premium API Access",
        "description": "Real-time data access",
        "payGateType": "credit",
        "totalCredits": 5
      }
    }
  ],
  "pagination": {
    "totalCount": 156,
    "limit": 20,
    "offset": 0,
    "hasNext": true,
    "hasPrev": false
  },
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

PayGate Access

Standard Payment Flow

Access any PayGate using its short code. PayGates support the HTTP methods they were configured with:

GET /{shortCode}
POST /{shortCode}
PUT /{shortCode}
DELETE /{shortCode}
PATCH /{shortCode}

// First request - returns 402 Payment Required
HTTP/1.1 402 Payment Required
{
  "x402": {
    "token": "payment_token_here",
    "amount": "0.01",
    "address": "0x742d35Cc6634C0532925a3b8c2414F4e456C10F4"
  }
}

// If using unsupported method - returns 400 Bad Request
HTTP/1.1 400 Bad Request
{
  "error": {
    "type": "validation",
    "code": "METHOD_NOT_ALLOWED",
    "message": "Method PUT not allowed for this route. Allowed: GET, POST"
  }
}

// Retry with payment proof
GET /{shortCode}
X-Payment: <payment_proof>

// Returns proxied response from target URL

Authentication-Required PayGate

For PayGates with requireAuth: true:

// First request - returns 401 if no auth
GET /{shortCode}

HTTP/1.1 401 Unauthorized
{
  "error": {
    "type": "authentication",
    "code": "AUTH_REQUIRED",
    "message": "This route requires user authentication. Please include a valid Authorization header."
  }
}

// Request with auth - returns 402 for payment
GET /{shortCode}
Authorization: Bearer <token>

HTTP/1.1 402 Payment Required
{
  "x402": {
    "token": "payment_token_here",
    "amount": "0.05",
    "address": "0x742d35Cc6634C0532925a3b8c2414F4e456C10F4"
  }
}

// Request with both auth and payment
GET /{shortCode}
Authorization: Bearer <token>
X-Payment: <payment_proof>

// Returns proxied response from target URL

Health Check

API Health

GET /api/v1/health

Response:
{
  "status": "ok",
  "version": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Response Format

All errors return structured responses:

{
  "error": {
    "type": "validation|authentication|payment|server",
    "code": "SPECIFIC_ERROR_CODE",
    "message": "Human-readable error description"
  },
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Common HTTP status codes:

400 - Bad Request (validation errors)
401 - Unauthorized (missing or invalid authentication)
402 - Payment Required (x402 flow initiation)
403 - Forbidden (valid auth but insufficient permissions)
404 - Not Found (PayGate or resource not found)
429 - Too Many Requests (rate limiting)
500 - Internal Server Error

PreviousRate Limiting NextData Types & Models

Last updated 3 months ago

hashtagOverview

hashtagBase URL

hashtagAuthentication

hashtagAuthentication Flow

hashtagGet Authentication Message

hashtagLogin with Wallet Signature

hashtagRefresh Token

hashtagGet Current User

hashtagLogout

hashtagPayGate Management APIs

hashtagList PayGates

hashtagCreate PayGate (URL)

hashtagMulti-Method PayGates

hashtagCreate PayGate (File)

hashtagGet Specific PayGate

hashtagUpdate PayGate

hashtagUpdate PayGate Secret

hashtagDelete PayGate

hashtagTransfer API

hashtagExecute USDC Transfer

hashtagPremium PayGates API

hashtagCreate Premium PayGate

hashtagExtend Premium PayGate

hashtagDashboard API

hashtagGet Statistics

hashtagAccount Management API

hashtagGet Account Tier Information

hashtagGet Billing Information

hashtagUpdate Account Tier

hashtagTransaction History API

hashtagGet Transaction History

hashtagPayGate Access

hashtagStandard Payment Flow

hashtagAuthentication-Required PayGate

hashtagHealth Check

hashtagAPI Health

hashtagError Response Format

Overview

Base URL

Authentication

Authentication Flow

Get Authentication Message

Login with Wallet Signature

Refresh Token

Get Current User

Logout

PayGate Management APIs

List PayGates

Create PayGate (URL)

Multi-Method PayGates

Create PayGate (File)

Get Specific PayGate

Update PayGate

Update PayGate Secret

Delete PayGate

Transfer API

Execute USDC Transfer

Premium PayGates API

Create Premium PayGate

Extend Premium PayGate

Dashboard API

Get Statistics

Account Management API

Get Account Tier Information

Get Billing Information

Update Account Tier

Transaction History API

Get Transaction History

PayGate Access

Standard Payment Flow

Authentication-Required PayGate

Health Check

API Health

Error Response Format