x402-hub API Reference

Base URL

Production: https://hub.sigwei.com

Authentication

x402-hub uses two authentication patterns:

Bearer Token (for Auth and History endpoints):
```
Authorization: Bearer <JWT_TOKEN>
```
No Authentication (for Protocol endpoints):
- Protocol endpoints are public and don't require authentication

Authentication Endpoints

Get Authentication Message

GET /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"
}

Query Parameters:

walletAddress (required): Ethereum wallet address (EIP-55 checksum format recommended)

Response Fields:

message: SIWE-compliant message to sign
apiVersion: API version
timestamp: ISO 8601 timestamp

SIWE Compliance: Messages follow the Sign-In with Ethereum (EIP-4361) standard.

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",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Request Body:

message (required): The full SIWE message from /auth/message
signature (required): Wallet signature of the message

Response Fields:

accessToken: JWT token for authenticated requests (15 min expiry)
refreshToken: Token for refreshing access token (7 days expiry)
user: User information
apiVersion: API version
timestamp: ISO 8601 timestamp

Refresh Token

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

{
  "refreshToken": "your_refresh_token"
}

Response:
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "new_refresh_token",
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Request Body:

refreshToken (required): The refresh token from login

Response Fields:

accessToken: New JWT access token
refreshToken: New refresh token
apiVersion: API version
timestamp: ISO 8601 timestamp

Get Current User

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

Response:
{
  "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"
}

Headers:

Authorization: Bearer token (required)

Logout

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

Response:
{
  "success": true,
  "message": "Logged out successfully",
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Headers:

Authorization: Bearer token (required)

Transaction History Endpoints

Get Transaction History

GET /api/v1/history?limit=20&offset=0&network=base
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" or "base-sepolia")

Response:
{
  "success": true,
  "history": [
    {
      "id": 123,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:35:00Z",
      "signerAddress": "0x742d35cc6634c0532925a3b8c2414f4e456c10f4",
      "amount": "1000000",
      "network": "base",
      "chainId": 8453,
      "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
    }
  ],
  "pagination": {
    "totalCount": 156,
    "limit": 20,
    "offset": 0,
    "hasNext": true,
    "hasPrev": false
  },
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

Headers:

Authorization: Bearer token (required)

Query Parameters:

limit (required): 1-100
offset (optional): Default 0
network (optional): "base" or "base-sepolia"

Response Fields:

success: Boolean indicating success
history: Array of transaction history items
pagination: Pagination information
- totalCount: Total number of transactions
- limit: Requested limit
- offset: Requested offset
- hasNext: Whether there are more results
- hasPrev: Whether there are previous results
apiVersion: API version
timestamp: ISO 8601 timestamp

Transaction History Item Fields:

id: Unique transaction ID
createdAt: Transaction creation time
updatedAt: Last update time
signerAddress: Wallet address that signed
amount: Amount in wei (6 decimals for USDC)
network: Network name ("base" or "base-sepolia")
chainId: Blockchain chain ID
transactionHash: On-chain transaction hash (null if pending)
status: "pending", "success", or "failed"
error: Error message (null if no error)
type: "transfer" or "purchase"
x402Data: x402 protocol data
purchaseData: PayGate purchase data (only for 402ify purchases)

Protocol Endpoints

All x402 protocol endpoints support both EVM (Ethereum Virtual Machine) networks like Base and Solana (SVM) networks. The payload structure differs between the two, but the API endpoints and response formats are consistent.

Check Supported Networks

GET /supported

Response:
{
  "kinds": [
    {
      "scheme": "exact",
      "network": "base",
      "assets": [
        {
          "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "name": "USDC",
          "symbol": "USDC",
          "decimals": 6
        }
      ]
    },
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "assets": [
        {
          "address": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
          "name": "USDC",
          "symbol": "USDC",
          "decimals": 6
        }
      ]
    }
  ]
}

Response Fields:

kinds: Array of supported payment kinds
- scheme: Payment scheme ("exact")
- network: Network name
- assets: Supported assets on this network
  - address: Token contract address
  - name: Token name
  - symbol: Token symbol
  - decimals: Token decimals

Verify Payment

Verifies a payment for both EVM and Solana networks.

EVM (Ethereum/Base) Example:

POST /verify
Content-Type: application/json

{
  "x402Version": 1,
  "paymentPayload": {
    "scheme": "exact",
    "network": "base",
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0xSender",
        "to": "0xRecipient",
        "value": "1000000",
        "validAfter": "0",
        "validBefore": "9999999999",
        "nonce": "0x..."
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "base",
    "exact": {
      "from": "0xSender",
      "to": "0xRecipient",
      "amount": "1000000",
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    }
  }
}

Solana Example:

POST /verify
Content-Type: application/json

{
  "x402Version": 1,
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "solana-devnet",
    "payload": {
      "transaction": "base64_encoded_solana_transaction"
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "solana-devnet",
    "maxAmountRequired": "1000000",
    "resourceUrl": "https://sigwei.com",
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "extra": {
      "feePayer": "FeePayerPublicKey..."
    }
  }
}

Response (same for both EVM and Solana):

{
  "isValid": true,
  "invalidReason": null
}

Request Body:

x402Version: Protocol version (always 1)
paymentPayload: Payment data from payer (EVM or Solana structure)
paymentRequirements: Payment requirements from payee

Response Fields:

isValid: Boolean indicating if payment is valid
invalidReason: Error message if invalid (null if valid)

Settle Payment

Settles a payment for both EVM and Solana networks.

EVM (Ethereum/Base) Example:

POST /settle
Content-Type: application/json

{
  "x402Version": 1,
  "paymentPayload": {
    "scheme": "exact",
    "network": "base",
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0xSender",
        "to": "0xRecipient",
        "value": "1000000",
        "validAfter": "0",
        "validBefore": "9999999999",
        "nonce": "0x..."
      }
    }
  },
  "paymentRequirements": { ... },
  "confirm": true,
  "useDbId": false
}

Solana Example:

POST /settle
Content-Type: application/json

{
  "x402Version": 1,
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "solana-devnet",
    "payload": {
      "transaction": "base64_encoded_solana_transaction"
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "solana-devnet",
    "maxAmountRequired": "1000000",
    "resourceUrl": "https://sigwei.com",
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "extra": {
      "feePayer": "FeePayerPublicKey..."
    }
  },
  "confirm": true,
  "useDbId": false
}

Response (same for both EVM and Solana):

{
  "status": "success",
  "transaction": "0x1325a7b20147c57dab8c3f3f1234567890abcdef...",
  "network": "base",
  "amount": "1000000"
}

Request Body:

x402Version: Protocol version (always 1)
paymentPayload: Payment data from payer (EVM or Solana structure)
paymentRequirements: Payment requirements from payee
confirm (optional): Enable on-chain verification (default: false)
useDbId (optional): Return database ID instead of tx hash (default: false)

Response Fields:

status: "success" or "failed"
transaction: Transaction hash or database ID
network: Network name
amount: Amount settled in base units (wei for EVM, lamports for Solana)

Transfer

Executes a transfer for both EVM and Solana networks.

EVM (Ethereum/Base) Example:

POST /transfer
Content-Type: application/json

{
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0xSender",
      "to": "0xRecipient",
      "value": "1000000",
      "validAfter": "0",
      "validBefore": "9999999999",
      "nonce": "0x..."
    }
  },
  "network": "base",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "confirm": true
}

Solana Example:

POST /transfer
Content-Type: application/json

{
  "payload": {
    "transaction": "base64_encoded_solana_transaction"
  },
  "network": "solana-devnet",
  "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": 1000000,
  "recipient": "RecipientPublicKey...",
  "confirm": true
}

Response (same for both EVM and Solana):

{
  "status": "success",
  "transaction": "0x1325a7b20147c57dab8c3f3f1234567890abcdef...",
  "network": "base",
  "amount": "1000000"
}

Request Body:

payload: Transfer payload (EVM or Solana structure)
- EVM: Contains signature and authorization with transfer details
- Solana: Contains transaction (base64-encoded pre-signed transaction)
network: Network name (e.g., "base", "base-sepolia", "solana-devnet")
asset: Token address (EVM) or mint address (Solana)
amount (required for Solana): Transfer amount in base units
recipient (required for Solana): Recipient wallet address
confirm (optional): Enable on-chain verification (default: false)

Response Fields:

status: "success" or "failed"
transaction: Transaction hash or signature
network: Network name
amount: Amount transferred in base units

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

200 - OK (successful request)
400 - Bad Request (validation errors)
401 - Unauthorized (missing or invalid authentication)
403 - Forbidden (valid auth but insufficient permissions)
404 - Not Found
500 - Internal Server Error

Common Error Codes

Authentication Errors (401):

AUTH_REQUIRED - Authentication required but not provided
INVALID_TOKEN - JWT token is invalid or expired
INVALID_SIGNATURE - Wallet signature verification failed

Validation Errors (400):

INVALID_ADDRESS - Invalid Ethereum address
INVALID_AMOUNT - Invalid amount specified
INVALID_NETWORK - Unsupported network
MISSING_PARAMETER - Required parameter missing

Payment Errors (400):

PAYMENT_INVALID - Payment verification failed
INSUFFICIENT_FUNDS - Not enough balance
NONCE_ALREADY_USED - Nonce has been used

Rate Limiting

x402-hub does not currently implement rate limiting. However, clients should implement reasonable retry logic and avoid excessive requests.

Pagination

The history endpoint supports pagination:

GET /api/v1/history?limit=20&offset=0  # First page
GET /api/v1/history?limit=20&offset=20 # Second page
GET /api/v1/history?limit=20&offset=40 # Third page

Use the pagination object in responses to determine if more pages exist:

{
  "pagination": {
    "totalCount": 156,
    "limit": 20,
    "offset": 0,
    "hasNext": true,
    "hasPrev": false
  }
}

Network Information

EVM Networks

Base Mainnet

Network: base
Chain ID: 8453
USDC Contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Base Sepolia Testnet

Network: base-sepolia
Chain ID: 84532
USDC Contract: 0x036CbD53842c5426634e7929541eC2318f3dCF7e

Solana Networks

Solana Devnet

Network: solana-devnet
USDC Mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
RPC: https://api.devnet.solana.com

Solana Mainnet

Network: solana-mainnet
USDC Mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
RPC: https://api.mainnet-beta.solana.com

PreviousHubClient SDK (Go)NextGetting Started with 402ify

Last updated 22 days ago

Base URL

Authentication

Authentication Endpoints

Get Authentication Message

Login with Wallet Signature

Refresh Token

Get Current User

Logout

Transaction History Endpoints

Get Transaction History

Protocol Endpoints

Check Supported Networks

Verify Payment

Settle Payment

Transfer

Error Response Format

Common HTTP Status Codes

Common Error Codes

Rate Limiting

Pagination

Network Information

EVM Networks

Solana Networks

Related Documentation