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.

Login with Wallet Signature

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 LimitingNextData Types & Models

Last updated