Getting Started with x402-hub

Overview

x402-hub is the foundational payment infrastructure service that implements the x402 protocol for blockchain payments. It provides protocol endpoints, wallet authentication, and transaction history.

Multi-Chain Support: x402-hub supports both EVM networks (Ethereum, Base) and Solana networks, allowing you to process payments across multiple blockchains using a single, consistent API.

Base URL

• Production: https://hub.sigwei.com

All endpoints use standard x402 protocol paths or /api/v1/ prefix for hub-specific features.

Integration Options

You can integrate with x402-hub in three ways:

1. HubClient SDK (Go) - Recommended for Go applications

2. REST API - For any language with HTTP support

3. x402 Protocol - Standard x402-compatible clients

Quick Start with HubClient (Go)

Installation

go get github.com/sigweihq/x402pay

Basic Usage

package main

import (
    "fmt"
    "github.com/sigweihq/x402pay/pkg/hubclient"
    x402paytypes "github.com/sigweihq/x402pay/pkg/types"
)

func main() {
    // Create client with default hub URL (https://hub.sigwei.com)
    client := hubclient.NewHubClient(nil)

    // Or specify custom URL
    // client := hubclient.NewHubClient(&types.FacilitatorConfig{
    //     URL: "https://custom-hub.example.com",
    // })

    // Use the client...
}

See HubClient SDK Documentation for complete SDK usage.

Quick Start with REST API

Prerequisites

• Wallet: Ethereum-compatible wallet with private key

• USDC Balance: USDC on Base blockchain for transfers

• HTTP Client: curl, axios, requests, or similar

1. Authentication Flow

Get Authentication Message

curl "https://hub.sigwei.com/api/v1/auth/message?walletAddress=0xYOUR_WALLET"

Response:

{
  "message": "hub.sigwei.com wants you to sign in with your Ethereum account:\n0x742D35Cc6634C19D8B4e8d5C1234567890123456\n\nURI: https://hub.sigwei.com\nVersion: 1\nChain ID: 8453\nNonce: abc123...\nIssued At: 2024-01-15T10:30:00Z",
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Sign Message with Wallet

Use your wallet software (ethers.js, web3.py, etc.) to sign the message:

// ethers.js example
const signature = await wallet.signMessage(message);

Login with Signature

curl -X POST https://hub.sigwei.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "message": "FULL_SIGNED_MESSAGE",
    "signature": "0x1234567890abcdef..."
  }'

Response:

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

2. Query Transaction History

curl -X GET "https://hub.sigwei.com/api/v1/history?limit=10&network=base" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "success": true,
  "history": [
    {
      "id": 123,
      "createdAt": "2024-01-15T10:30:00Z",
      "signerAddress": "0x742d35cc6634c0532925a3b8c2414f4e456c10f4",
      "amount": "1000000",
      "network": "base",
      "transactionHash": "0x1234...",
      "status": "success",
      "type": "transfer"
    }
  ],
  "pagination": {
    "totalCount": 156,
    "limit": 10,
    "offset": 0,
    "hasNext": true,
    "hasPrev": false
  },
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

3. Execute Transfer

curl -X POST https://hub.sigwei.com/transfer \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0xYOUR_WALLET",
        "to": "0xRECIPIENT_WALLET",
        "value": "1000000",
        "validAfter": "0",
        "validBefore": "9999999999",
        "nonce": "0x..."
      }
    },
    "network": "base",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "confirm": true
  }'

Core Endpoints

x402 Protocol Endpoints

x402-hub implements the standard x402 protocol:

• GET /supported - Query supported networks and schemes

• POST /verify - Verify payment without settling

• POST /settle - Settle payment on blockchain

• POST /transfer - Convenient transfer endpoint

Hub-Specific Endpoints

Authentication and history (require /api/v1/ prefix):

• GET /api/v1/auth/message - Get authentication message

• POST /api/v1/auth/login - Login with wallet signature

• POST /api/v1/auth/refresh - Refresh access token

• GET /api/v1/auth/me - Get current user

• POST /api/v1/auth/logout - Logout

• GET /api/v1/history - Query transaction history

Common Use Cases

For Payment Processors

Build payment-enabled applications that verify and settle blockchain payments:

// Verify payment
verifyResp, _ := client.Verify(paymentPayload, paymentRequirements)
if verifyResp.IsValid {
    // Payment is valid, proceed with service
}

// Settle payment
settleResp, _ := client.Settle(paymentPayload, paymentRequirements)
fmt.Println("Transaction hash:", settleResp.Transaction)

For Transaction Tracking

Query and monitor blockchain transactions:

// Authenticate user
msgResp, _ := client.Auth.GetAuthMessage(walletAddress)
signature := signWithWallet(msgResp.Message)
client.Auth.Login(msgResp.Message, signature)

// Get transaction history
history, _ := client.History.GetHistory(&x402paytypes.HistoryParams{
    Network: "base",
    Limit:   50,
})

for _, tx := range history.Transactions {
    fmt.Printf("Transaction: %s (%s)\n", tx.Status, tx.Network)
}

For Gasless Transfers

Execute USDC transfers without gas fees:

// Create transfer payload
payload := &types.ExactEvmPayload{
    Signature: "0x...",
    Authorization: types.Authorization{
        From:        "0xSender",
        To:          "0xRecipient",
        Value:       "1000000", // 1 USDC
        ValidAfter:  "0",
        ValidBefore: "9999999999",
        Nonce:       "0x...",
    },
}

// Execute transfer
resp, _ := client.Transfer(payload, "base", assetAddress, true)
fmt.Println("Transfer complete:", resp.Transaction)

Network Support

x402-hub supports both EVM and Solana networks:

EVM Networks

• Base Mainnet (network: "base")

  • Chain ID: 8453

  • USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

• Base Sepolia Testnet (network: "base-sepolia")

  • Chain ID: 84532

  • USDC: 0x036CbD53842c5426634e7929541eC2318f3dCF7e

Solana Networks

• Solana Devnet (network: "solana-devnet")

  • USDC Mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

• Solana Mainnet (network: "solana-mainnet")

  • USDC Mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Authentication

x402-hub uses two authentication methods:

1. Wallet Signature (SIWE) - For user authentication

   • Used by Auth endpoints (/api/v1/auth/*)

   • Used by History endpoint (/api/v1/history)

   • Returns JWT access tokens

2. No Authentication - For protocol endpoints

   • Used by x402 protocol endpoints (/verify, /settle, /transfer, /supported)

   • Public endpoints for payment processing

Error Handling

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)

• 403 - Forbidden (insufficient permissions)

• 404 - Not Found

• 500 - Internal Server Error

Next Steps

• Go Developers: See HubClient SDK Documentation

• API Reference: See x402-hub API Reference

• x402 Protocol: See x402 Protocol Reference

• 402ify Integration: See Getting Started with 402ify

Need Help?

Check out our Support & Resources section for troubleshooting and additional resources.