agirails-patterns

AGIRAILS SDK Patterns (v4.0)

The AGIRAILS SDK provides a multi-level API with intelligent adapter routing. Payments are routed automatically based on the to parameter, so you pick the right level of abstraction for your needs and the SDK handles the rest.

Quickstart (Copy-Paste-Run)

Install and run in 30 seconds — no wallet, no keys, no config:

npm install @agirails/sdk

Save as quickstart.js and run with node quickstart.js:

const { ACTPClient } = require('@agirails/sdk');

async function main() {
  // Create client in mock mode (no blockchain, no keys needed)
  const client = await ACTPClient.create({ mode: 'mock' });
  console.log('Address:', client.getAddress());

  // Mint test USDC (mock only — starts with 0 balance)
  await client.mintTokens(client.getAddress(), '10000000000'); // 10,000 USDC
  const balance = await client.getBalance(client.getAddress());
  console.log('Balance:', balance, 'wei (', Number(balance) / 1e6, 'USDC)');

  // Pay a provider (escrow flow)
  const result = await client.pay({
    to: '0x0000000000000000000000000000000000000001',
    amount: '5.00', // 5 USDC (human-readable, not wei)
  });
  console.log('Payment created:', result.txId);
  console.log('State:', result.state); // COMMITTED
  console.log('Escrow ID:', result.escrowId);
  console.log('Release required:', result.releaseRequired);
}

main().catch(console.error);

Output:

Address: 0x... (random mock address)
Balance: 10000000000 wei ( 10000 USDC)
Payment created: 0x... (transaction hash)
State: COMMITTED
Escrow ID: 0x...
Release required: true

Next steps: Replace mock with testnet (add ACTP_PRIVATE_KEY env var) or mainnet for production.

Adapter Routing (Most Important Pattern)

The SDK inspects the to parameter and routes to the correct payment adapter automatically:

to value	Adapter	Registration	Settlement
0x1234... (address)	ACTP escrow	Default, always available	Lock / hold / release
https://... (URL)	x402 instant	Must register X402Adapter	Single atomic transfer
agent ID (number)	ERC-8004 resolve then ACTP	Must configure ERC-8004 bridge	Lock / hold / release