Skip to main content
GET
/
x402
/
transactions
/
{walletAddress}
/api/v1/x402/transactions/{walletAddress}
curl --request GET \
  --url https://api.venice.ai/api/v1/x402/transactions/{walletAddress} \
  --header 'X-Sign-In-With-X: <api-key>'
{
  "success": true,
  "data": {
    "walletAddress": "0xyour_wallet_address",
    "currentBalance": 12.35,
    "transactions": [
      {
        "id": "ledger_01HZY8M4W4Y6QZ8B6Q4P0V3J2K",
        "amount": -0.15,
        "balanceAfter": 12.35,
        "type": "TOP_UP",
        "createdAt": "2026-04-03T12:34:56.000Z",
        "requestId": "<string>",
        "modelId": "<string>"
      }
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "hasMore": false
    }
  }
}

Authorizations

​
X-Sign-In-With-X
string
header
required

Wallet-based authentication using the x402 protocol (Sign-In-With-X / EIP-4361 SIWE).

Header format: Base64-encoded JSON object with the following fields:

  • address — Ethereum wallet address (checksummed)
  • message — EIP-4361 SIWE message string (created with SiweMessage.prepareMessage())
  • signature — Hex-encoded signature of the message, signed by the wallet's private key
  • timestamp — Unix timestamp in milliseconds
  • chainId — Chain ID (use 8453 for Base)

SIWE message fields:

  • domain: outerface.venice.ai
  • uri: https://outerface.venice.ai
  • version: "1"
  • chainId: 8453
  • nonce: Random 16-character hex string
  • issuedAt / expirationTime: ISO timestamps (recommended TTL: 10 minutes)
  • statement: "Sign in to Venice API"

Example (TypeScript):

import { Wallet } from 'ethers'
import { SiweMessage } from 'siwe'

const wallet = new Wallet(PRIVATE_KEY)
const msg = new SiweMessage({ domain: 'outerface.venice.ai', address: wallet.address, statement: 'Sign in to Venice API', uri: 'https://outerface.venice.ai', version: '1', chainId: 8453, nonce: crypto.randomUUID().replace(/-/g, '').slice(0, 16), issuedAt: new Date().toISOString(), expirationTime: new Date(Date.now() + 600000).toISOString() })
const signature = await wallet.signMessage(msg.prepareMessage())
const header = btoa(JSON.stringify({ address: wallet.address, message: msg.prepareMessage(), signature, timestamp: Date.now(), chainId: 8453 }))
// Set header: X-Sign-In-With-X: <header>

SDK: npm install @venice-ai/x402-client provides VeniceClient and createAuthFetch which handle this automatically.

Billing: x402 users pay from a prepaid USDC credit balance. Top up via POST /x402/top-up. When balance is insufficient, endpoints return 402 with structured top-up instructions.

Headers

​
X-Sign-In-With-X
string
required

base64-encoded JSON SIWE payload message proving wallet ownership

Example:

"siwx_example_token"

Path Parameters

​
walletAddress
string
required

Ethereum wallet address.

Pattern: ^0x[a-fA-F0-9]{40}$
Example:

"0xYOUR_WALLET_ADDRESS"

Query Parameters

​
limit
integer
default:50

Maximum number of transactions to return.

Required range: 1 <= x <= 100
Example:

50

​
offset
integer | null
default:0

Number of transactions to skip before returning results.

Required range: x >= 0
Example:

0

Response

x402 transaction history for the wallet.

​
success
enum<boolean>
required
Available options:
true
​
data
object
required