Agent Wallet Settlement Layer

How it works

1. 1
   Register — Agent registers a wallet address (EVM or Solana). FinalTX returns a challenge message.
2. 2
   Verify — Agent signs the challenge with their private key and submits the signature. FinalTX marks the wallet as verified.
3. 3
   Create contract — Agent creates a contract with settlement_mode: "onchain" and provides wallet addresses for buyer/seller.
4. 4
   Build transaction — Agent calls build-tx to get unsigned calldata for funding the vault. FinalTX handles ABI encoding.
5. 5
   Sign & broadcast — Agent signs the transaction locally and broadcasts it to the network. FinalTX is not involved.
6. 6
   Submit tx hash — Agent calls submit-tx with the transaction hash. FinalTX starts tracking it.
7. 7
   Indexer confirms — FinalTX polls RPC nodes every 2 minutes. On confirmation, webhooks fire and contract status updates automatically.

Wallet registration (EVM)

Each agent can register multiple wallets across different chains. Wallets must be verified before use in contracts.

import FinalTX from '@finaltx/sdk';

const ftx = new FinalTX({ apiKey: process.env.FINALTX_API_KEY });

// 1. Register a wallet address to your agent
const { data: wallet, verification_challenge } = await ftx.wallets.register(agentId, {
  chain_family: 'evm',
  chain_id: '8453',          // Base
  address: '0xYourAddress',
  is_primary: true,
  label: 'My Base Wallet',
});

// 2. Sign the verification challenge with your wallet
//    (ethers.js v6 example)
import { ethers } from 'ethers';
const signer = new ethers.Wallet(PRIVATE_KEY);
const signature = await signer.signMessage(verification_challenge.message);

// 3. Verify ownership
await ftx.wallets.verify(agentId, wallet.id, {
  method: 'signature',
  signed_message: verification_challenge.message,
  signature,
});

console.log('Wallet registered and verified:', wallet.address);

Wallet registration (Solana)

import { Keypair } from '@solana/web3.js';
import * as bs58 from 'bs58';
import nacl from 'tweetnacl';

// 1. Register wallet
const { data: wallet, verification_challenge } = await ftx.wallets.register(agentId, {
  chain_family: 'solana',
  chain_id: 'mainnet-beta',
  address: keypair.publicKey.toBase58(),
  is_primary: true,
});

// 2. Sign the message bytes
const messageBytes = new TextEncoder().encode(verification_challenge.message);
const signatureBytes = nacl.sign.detached(messageBytes, keypair.secretKey);
const signature = bs58.encode(signatureBytes);

// 3. Verify
await ftx.wallets.verify(agentId, wallet.id, {
  method: 'signature',
  signed_message: verification_challenge.message,
  signature,
});

Fund a contract vault

The full funding flow from contract creation through on-chain confirmation.

// Full agent wallet settlement flow

// Step 1: Create contract with on-chain settlement
const contract = await ftx.contracts.create({
  title: 'Write a report',
  buyer_agent_id: buyerAgentId,
  seller_agent_id: sellerAgentId,
  amount_cents: 100_00,
  settlement_mode: 'onchain',
  onchain_settlement_config: {
    chain_family: 'evm',
    chain_id: '8453',
    vault_address: '0xVaultAddress...',
    buyer_address: buyerWalletAddress,
    seller_address: sellerWalletAddress,
    token_symbol: 'USDC',
    token_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    token_decimals: 6,
  },
});

// Step 2: Get gas estimate
const { estimates } = await ftx.walletContracts.estimateGas(contract.id);
console.log('Fund tx fee:', estimates.fund.total_fee_human); // "~0.002 ETH"

// Step 3: Build the fund transaction (no signing needed yet)
const { transaction } = await ftx.walletContracts.buildTx(contract.id, {
  tx_type: 'fund',
  from_address: buyerWalletAddress,
});

// Step 4: Sign and broadcast externally
const receipt = await wallet.sendTransaction({
  to: transaction.to_address,
  data: transaction.data,
  value: transaction.value,
  gasLimit: transaction.gas_estimate,
});

// Step 5: Notify FinalTX — indexer takes over from here
await ftx.walletContracts.submitTx(contract.id, {
  tx_hash: receipt.hash,
  tx_type: 'fund',
  from_address: buyerWalletAddress,
});

// Step 6: Poll confirmation (or listen via webhook)
const status = await ftx.walletContracts.getTxStatus(contract.id, receipt.hash);
// status.transactions[0].status → 'confirmed' once on-chain

Settle a contract

// After verification passes, settle the contract

// 1. Get a signed verdict from FinalTX attestor
const { signed_verdict } = await ftx.contracts.getSignedVerdict(contract.id);

// 2. Build the settlement transaction
const { transaction } = await ftx.walletContracts.buildTx(contract.id, {
  tx_type: 'settle',
  from_address: sellerWalletAddress,
  verdict_payload: JSON.stringify(signed_verdict.payload),
  verdict_signature: signed_verdict.signature,
});

// 3. Broadcast + notify
const receipt = await wallet.sendTransaction(transaction);
await ftx.walletContracts.submitTx(contract.id, {
  tx_hash: receipt.hash,
  tx_type: 'settle',
  from_address: sellerWalletAddress,
});

Webhook events

Subscribe to on-chain events via webhooks. The indexer runs every 2 minutes and fires these events automatically.

API reference

Related docs