Example Flows

Example Flows

Complete code examples for common use cases.

---

Setup

Dependencies

npm install viem

Configuration

import { createWalletClient, http, keccak256, toHex } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const GATEWAY_URL = 'https://x402.quickintel.io';
const PRIVATE_KEY = process.env.WALLET_PRIVATE_KEY;
const PROVIDER_NAME = 'my-trading-agent';

const account = privateKeyToAccount(PRIVATE_KEY);
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http()
});

---

Pricing Reminder

Call Type	Cost
Any /v1/tator/prompt call	$0.20
Job polling (/v1/tator/jobs/:id)	Free

⚠️ You are charged $0.20 per call regardless of outcome. Validate prompts before sending.

---

Example 1: Price Check (Info Query)

A simple informational query that doesn't require signing any transactions.

async function checkPrice(token, chain) {
  // Build a clear prompt with token AND chain
  const prompt = `What is the price of ${token} on ${chain}?`;
  
  const data = await submitPromptWithPayment(prompt);
  
  console.log('Type:', data.type);           // "info"
  console.log('Response:', data.response);   // "ETH is trading at $2,063..."
  
  return data;
}

// Usage
await checkPrice('ETH', 'base');
await checkPrice('0x4ed4e862860bed51a9570b96d89af5e1b0efefed', 'base'); // Use CA for obscure tokens

---

Example 2: Buy Token

Execute a token purchase and sign the resulting transaction.

async function buyToken(amountUsd, token, chain) {
  // Clear prompt with all required details
  const prompt = `Buy $${amountUsd} worth of ${token} on ${chain}`;
  
  const data = await submitPromptWithPayment(prompt);

  if (data.type !== 'transaction') {
    // Info or error response - no transaction to sign
    console.log('Response:', data.response);
    return data;
  }

  // Sign and broadcast transactions
  console.log(`Executing ${data.transactions.length} transaction(s)...`);

  for (const tx of data.transactions) {
    console.log(`  ${tx.sequence}: ${tx.description}`);
    
    const hash = await walletClient.sendTransaction({
      to: tx.to,
      data: tx.data,
      value: BigInt(tx.value),
      gas: BigInt(tx.gas),
      chain: { id: tx.chainId }
    });

    console.log(`  TX Hash: ${hash}`);
    
    // Wait for confirmation
    const receipt = await walletClient.waitForTransactionReceipt({ hash });
    console.log(`  Confirmed in block ${receipt.blockNumber}`);
  }

  console.log('Trade complete!');
  return data;
}

// Usage
await buyToken(10, 'ETH', 'base');
await buyToken(50, 'PEPE', 'ethereum');

---

Example 3: Swap Tokens

Swap between two tokens.

async function swapTokens(amount, fromToken, toToken, chain) {
  // Include all details in prompt
  const prompt = `Swap ${amount} ${fromToken} for ${toToken} on ${chain}`;
  
  const data = await submitPromptWithPayment(prompt);

  if (data.type === 'transaction') {
    for (const tx of data.transactions) {
      const hash = await walletClient.sendTransaction({
        to: tx.to,
        data: tx.data,
        value: BigInt(tx.value),
        gas: BigInt(tx.gas),
        chain: { id: tx.chainId }
      });
      await walletClient.waitForTransactionReceipt({ hash });
    }
    
    console.log(`Swapped ${amount} ${fromToken} → ${data.transaction_data.quote.outputAmount} ${toToken}`);
  }

  return data;
}

// Usage
await swapTokens(100, 'USDC', 'ETH', 'arbitrum');
await swapTokens(0.5, 'ETH', 'USDC', 'base');

---

Example 4: Bridge Assets

Bridge tokens between chains.

async function bridgeAssets(amount, token, fromChain, toChain) {
  // Specify both source and destination chains
  const prompt = `Bridge ${amount} ${token} from ${fromChain} to ${toChain}`;
  
  const data = await submitPromptWithPayment(prompt);

  if (data.type === 'transaction') {
    const tx = data.transactions[0];
    
    const hash = await walletClient.sendTransaction({
      to: tx.to,
      data: tx.data,
      value: BigInt(tx.value),
      gas: BigInt(tx.gas),
      chain: { id: tx.chainId }
    });
    
    console.log(`Bridge initiated: ${hash}`);
    console.log(`Estimated time: ${data.transaction_data.bridge.estimatedTime}`);
  }

  return data;
}

// Usage
await bridgeAssets(100, 'USDC', 'arbitrum', 'base');
await bridgeAssets(0.1, 'ETH', 'ethereum', 'optimism');

---

Example 5: Async Mode (Long Operations)

Use async mode for operations that may take longer.

async function executeAsync(prompt) {
  // Step 1: Submit with async flag
  const payment = await getPaymentHeader();
  
  const response = await fetch(`${GATEWAY_URL}/v1/tator/prompt`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'PAYMENT-SIGNATURE': payment
    },
    body: JSON.stringify({
      prompt,
      walletAddress: account.address,
      provider: PROVIDER_NAME,
      async: true  // Enable async mode
    })
  });

  const { jobId } = await response.json();
  console.log(`Job submitted: ${jobId}`);

  // Step 2: Poll for completion (FREE - no payment required)
  let result;
  while (true) {
    const pollRes = await fetch(
      `${GATEWAY_URL}/v1/tator/jobs/${jobId}?walletAddress=${account.address}`
    );
    result = await pollRes.json();

    if (result.status === 'completed' || result.status === 'failed') {
      break;
    }

    console.log('Still processing...');
    await sleep(2000);  // Wait 2 seconds
  }

  // Step 3: Handle result
  if (result.status === 'failed') {
    throw new Error(result.error);
  }

  if (result.type === 'transaction') {
    for (const tx of result.transactions) {
      const hash = await walletClient.sendTransaction({
        to: tx.to,
        data: tx.data,
        value: BigInt(tx.value),
        gas: BigInt(tx.gas),
        chain: { id: tx.chainId }
      });
      await walletClient.waitForTransactionReceipt({ hash });
    }
  }

  return result;
}

// Usage
await executeAsync('Buy $50 worth of PEPE on base');

---

Example 6: Validate Prompt Before Sending

Avoid wasting $0.20 on unclear prompts by validating first.

function validatePrompt(prompt) {
  const errors = [];
  const promptLower = prompt.toLowerCase();
  
  // Check for action
  const actions = ['buy', 'sell', 'swap', 'bridge', 'send', 'price', 'balance'];
  const hasAction = actions.some(a => promptLower.includes(a));
  if (!hasAction) {
    errors.push('Missing action (buy, sell, swap, bridge, send)');
  }
  
  // Check for chain
  const chains = ['base', 'ethereum', 'arbitrum', 'optimism', 'polygon', 'solana', 'avalanche'];
  const hasChain = chains.some(c => promptLower.includes(c));
  if (!hasChain && !promptLower.includes('on ')) {
    errors.push('Missing chain (e.g., "on base", "on ethereum")');
  }
  
  // Check for amount (for trading actions)
  const tradingActions = ['buy', 'sell', 'swap', 'bridge', 'send'];
  const isTrading = tradingActions.some(a => promptLower.includes(a));
  const hasAmount = /\$?\d+/.test(prompt);
  if (isTrading && !hasAmount) {
    errors.push('Missing amount (e.g., "$50", "100 USDC")');
  }
  
  return {
    valid: errors.length === 0,
    errors
  };
}

// Usage
const validation = validatePrompt('buy some crypto');
if (!validation.valid) {
  console.log('Invalid prompt:', validation.errors);
  // Don't send - would waste $0.20
} else {
  await submitPromptWithPayment(prompt);
}

---

Example 7: Token Safety Check

Check if a token is safe before trading.

async function checkTokenSafety(tokenAddress, chain) {
  const prompt = `Is ${tokenAddress} safe to trade on ${chain}? Do a security scan.`;
  
  const data = await submitPromptWithPayment(prompt);
  
  console.log('Safety Analysis:', data.response);
  
  // Check for red flags in the response
  const isSafe = !data.response.toLowerCase().includes('honeypot') &&
                 !data.response.toLowerCase().includes('scam') &&
                 !data.response.toLowerCase().includes('dangerous');
  
  return { safe: isSafe, analysis: data.response };
}

// Usage - costs $0.20 for the check
const { safe, analysis } = await checkTokenSafety('0x...', 'base');
if (safe) {
  // Additional $0.20 for the trade
  await buyToken(10, '0x...', 'base');
}

---

Helper Functions

Sign x402 Payment ($0.20)

async function signX402Payment(paymentInfo) {
  const nonce = keccak256(toHex(`${Date.now()}-${Math.random()}`));
  const validBefore = BigInt(Math.floor(Date.now() / 1000) + 3600);

  const domain = {
    name: paymentInfo.extra.name,
    version: paymentInfo.extra.version,
    chainId: 8453,  // Base
    verifyingContract: paymentInfo.asset
  };

  const types = {
    TransferWithAuthorization: [
      { name: 'from', type: 'address' },
      { name: 'to', type: 'address' },
      { name: 'value', type: 'uint256' },
      { name: 'validAfter', type: 'uint256' },
      { name: 'validBefore', type: 'uint256' },
      { name: 'nonce', type: 'bytes32' }
    ]
  };

  const message = {
    from: account.address,
    to: paymentInfo.payTo,
    value: BigInt(paymentInfo.maxAmountRequired),  // 200000 = $0.20
    validAfter: 0n,
    validBefore,
    nonce
  };

  const signature = await account.signTypedData({
    domain,
    types,
    primaryType: 'TransferWithAuthorization',
    message
  });

  const paymentPayload = {
    x402Version: 2,
    scheme: 'exact',
    network: 'eip155:8453',
    payload: {
      signature,
      authorization: {
        from: account.address,
        to: paymentInfo.payTo,
        value: paymentInfo.maxAmountRequired,
        validAfter: '0',
        validBefore: validBefore.toString(),
        nonce
      }
    }
  };

  return Buffer.from(JSON.stringify(paymentPayload)).toString('base64');
}

Submit Prompt with Payment

async function submitPromptWithPayment(prompt) {
  // Get 402 response
  const initialRes = await fetch(`${GATEWAY_URL}/v1/tator/prompt`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      prompt,
      walletAddress: account.address,
      provider: PROVIDER_NAME
    })
  });

  const { paymentRequired } = await initialRes.json();
  const paymentInfo = paymentRequired.accepts.find(a => a.network === 'eip155:8453');
  const payment = await signX402Payment(paymentInfo);

  // Submit with payment ($0.20)
  const response = await fetch(`${GATEWAY_URL}/v1/tator/prompt`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'PAYMENT-SIGNATURE': payment
    },
    body: JSON.stringify({
      prompt,
      walletAddress: account.address,
      provider: PROVIDER_NAME
    })
  });

  return response.json();
}

Sleep Helper

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

---

Error Handling

async function safeExecute(prompt) {
  // Validate first to avoid wasting $0.20
  const validation = validatePrompt(prompt);
  if (!validation.valid) {
    console.error('Invalid prompt:', validation.errors);
    return null;
  }

  try {
    const data = await submitPromptWithPayment(prompt);

    if (data.type === 'error' || data.status === 'failed') {
      console.error('API Error:', data.error);
      return null;
    }

    if (data.type === 'info' && data.transactions.length === 0) {
      // Clarification request or info response
      console.log('Info:', data.response);
      return data;
    }

    if (data.type === 'transaction') {
      for (const tx of data.transactions) {
        try {
          const hash = await walletClient.sendTransaction({
            to: tx.to,
            data: tx.data,
            value: BigInt(tx.value),
            gas: BigInt(tx.gas),
            chain: { id: tx.chainId }
          });
          await walletClient.waitForTransactionReceipt({ hash });
        } catch (txError) {
          console.error('Transaction failed:', txError.message);
        }
      }
    }

    return data;

  } catch (error) {
    console.error('Request failed:', error.message);
    return null;
  }
}

---

Full Working Example

import { keccak256, toHex } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { createWalletClient, http, createPublicClient } from 'viem';
import { base } from 'viem/chains';

// Config
const GATEWAY_URL = 'https://x402.quickintel.io';
const PRIVATE_KEY = process.env.WALLET_PRIVATE_KEY;
const PROVIDER_NAME = 'example-agent';

const account = privateKeyToAccount(PRIVATE_KEY);
const publicClient = createPublicClient({ chain: base, transport: http() });
const walletClient = createWalletClient({ account, chain: base, transport: http() });

async function main() {
  console.log(`Wallet: ${account.address}`);
  console.log(`Provider: ${PROVIDER_NAME}`);
  console.log(`Cost: $0.20 per API call\n`);

  // Check price first ($0.20)
  console.log('--- Price Check ($0.20) ---');
  const priceData = await submitPromptWithPayment('What is the price of ETH on base?');
  console.log(priceData.response);

  // Execute a small trade ($0.20)
  console.log('\n--- Executing Trade ($0.20) ---');
  const tradeData = await submitPromptWithPayment('Buy $5 worth of USDC on base');
  
  if (tradeData.type === 'transaction') {
    for (const tx of tradeData.transactions) {
      console.log(`Sending: ${tx.description}`);
      
      const hash = await walletClient.sendTransaction({
        to: tx.to,
        data: tx.data,
        value: BigInt(tx.value),
        gas: BigInt(tx.gas)
      });
      
      console.log(`TX: ${hash}`);
      const receipt = await publicClient.waitForTransactionReceipt({ hash });
      console.log(`Confirmed in block ${receipt.blockNumber}`);
    }
    
    console.log('\nTrade complete!');
    console.log(`Quote: ${JSON.stringify(tradeData.transaction_data.quote)}`);
  }
  
  console.log('\n--- Summary ---');
  console.log('Total API cost: $0.40 (2 calls × $0.20)');
}

main().catch(console.error);

---

Cost Summary

Operation	API Cost	Notes
Price check	$0.20	Info response
Token scan	$0.20	Info response
Buy/Sell/Swap	$0.20	Returns unsigned tx
Bridge	$0.20	Returns unsigned tx
Unclear prompt	$0.20	Returns clarification
Error	$0.20	Still charged
Job polling	Free	Poll as needed

---

Next Steps

• Join our Discord for support

• Check Quick Intel for token scanning

• View x402 Protocol documentation