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:

HubClient SDK (Go) - Recommended for Go applications
REST API - For any language with HTTP support
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);

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:

Wallet Signature (SIWE) - For user authentication
- Used by Auth endpoints (/api/v1/auth/*)
- Used by History endpoint (/api/v1/history)
- Returns JWT access tokens
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.

PreviousOverview NextHubClient SDK (Go)

Last updated 23 days ago

Overview

Base URL

Integration Options

Quick Start with HubClient (Go)

Installation

Basic Usage

Quick Start with REST API

Prerequisites

1. Authentication Flow

Get Authentication Message

Sign Message with Wallet

Login with Signature

2. Query Transaction History

3. Execute Transfer

Core Endpoints

x402 Protocol Endpoints

Hub-Specific Endpoints

Common Use Cases

For Payment Processors

For Transaction Tracking

For Gasless Transfers

Network Support

EVM Networks

Solana Networks

Authentication

Error Handling

Next Steps

Need Help?