Skip to main content

​
SettlementAgent

The SettlementAgent is the core class for creating agents that can send x402 payments on Solana. It supports both USDC and ATHR tokens.

​
Supported Tokens

TokenMint Address (Mainnet)DecimalsDescription
ATHR5abiPeWqRLYb21DWNGYRFwrABML24dYuGn39ZpPYpump6Native Aether token
USDCEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v6USD Coin stablecoin

​
Constructor

const agent = new SettlementAgent(merchantWallet?: string);
ParameterTypeDescription
merchantWalletstring (optional)Default recipient wallet for payments
If not provided, the agent looks for MERCHANT_WALLET_ADDRESS in environment variables.

​
Methods

​
init()

Initialize the agent with a wallet. 
await agent.init(wallet?: Keypair);
ParameterTypeDescription
walletKeypair (optional)Solana keypair. If not provided, loads from env
Example: 
import { Keypair } from '@solana/web3.js';

// Option 1: Load from environment
const agent = new SettlementAgent();
await agent.init();

// Option 2: Provide keypair directly
const keypair = Keypair.fromSecretKey(/* ... */);
await agent.init(keypair);

​
setMerchantWallet()

Set the recipient wallet dynamically. 
agent.setMerchantWallet(merchantWallet: string);
Useful when your agent needs to pay different recipients: 
const agent = new SettlementAgent();
await agent.init();

// Pay first merchant
agent.setMerchantWallet('Merchant1WalletAddress');
await agent.triggerSettlement(verification);

// Pay second merchant
agent.setMerchantWallet('Merchant2WalletAddress');
await agent.triggerSettlement(verification);

​
createSignedPayment()

Create a signed x402 payment that can be submitted by the recipient. Supports both ATHR and USDC tokens. 
const paymentHeader = await agent.createSignedPayment(
  recipientAddress: string,
  amount: number,
  options?: PaymentOptions
): Promise<string>;
ParameterTypeDescription
recipientAddressstringSolana wallet address of recipient
amountnumberAmount in tokens (e.g., 1.00 for 1 token)
optionsPaymentOptions (optional)Payment options including token type

​
PaymentOptions

interface PaymentOptions {
  token?: 'athr' | 'usdc';  // Default: 'usdc'
}
OptionTypeDefaultDescription
token'athr' | 'usdc''usdc'Token to use for payment
Returns: Base64-encoded x402 payment header Examples: 
// Pay with USDC (default)
const usdcPayment = await agent.createSignedPayment(
  'RecipientWalletAddress',
  0.50 // 0.50 USDC
);

// Pay with ATHR
const athrPayment = await agent.createSignedPayment(
  'RecipientWalletAddress',
  100, // 100 ATHR
  { token: 'athr' }
);

// Send to recipient in HTTP header
// X-Payment: <payment>

​
triggerSettlement()

Execute a settlement flow (internal use). 
await agent.triggerSettlement(verification: any);

​
Token Utilities

The SDK exports utility functions for working with tokens: 
import {
  getTokenMint,
  getTokenMintPublicKey,
  tokenToAmount,
  amountToToken,
  ATHR_MINT_MAINNET,
  USDC_MINT_MAINNET,
  TOKEN_DECIMALS
} from 'aether-agent-sdk';

// Get mint address for a token
const athrMint = getTokenMint('athr', true);  // mainnet
const usdcMint = getTokenMint('usdc', false); // devnet

// Convert amounts
const microAmount = tokenToAmount(1.5);  // 1500000
const tokenAmount = amountToToken(1500000); // 1.5

​
Payment Payload Structure

The x402 payment header contains: 
{
  "x402Version": 1,
  "scheme": "exact",
  "network": "solana-mainnet-beta",
  "payload": {
    "authorization": {
      "from": "PayerWalletAddress",
      "to": "RecipientWalletAddress",
      "value": "1000000",
      "asset": "5abiPeWqRLYb21DWNGYRFwrABML24dYuGn39ZpPYpump",
      "validBefore": 1704067200,
      "nonce": "unique-nonce-value"
    },
    "signedTransaction": "base64-encoded-transaction",
    "transactionMeta": {
      "blockhash": "...",
      "lastValidBlockHeight": 12345678
    }
  }
}
The asset field contains the token mint address (ATHR or USDC).

​
Environment Variables

VariableDescriptionRequired
SOLANA_NETWORKdevnet or mainnet-betaYes
SOLANA_RPC_URLCustom RPC endpointNo
AGENT_PRIVATE_KEYBase58 private keyYes*
AGENT_WALLET_PATHPath to keypair JSONYes*
ATHR_MINTATHR token mint addressNo
USDC_MINTUSDC token mint addressNo
MERCHANT_WALLET_ADDRESSDefault recipientNo
*One of AGENT_PRIVATE_KEY or AGENT_WALLET_PATH is required.

​
Error Handling

try {
  const payment = await agent.createSignedPayment(recipient, amount, { token: 'athr' });
} catch (error) {
  if (error.message.includes('Insufficient')) {
    console.log('Not enough token balance');
  } else if (error.message.includes('wallet not initialized')) {
    console.log('Agent wallet not configured');
  }
}

​
Best Practices

  1. Always initialize - Call init() before any operations
  2. Check balance - Ensure sufficient token balance before creating payments
  3. Handle expiration - Payments expire after maxTimeoutSeconds (default: 300s)
  4. Secure keys - Never commit private keys to version control
  5. Use ATHR for lower fees - ATHR payments have lower marketplace fees than USDC