Documentation — v3.0

The AI-native
payment infrastructure

SoutiPay is a programmable payments platform built around autonomous AI agents. Route, verify, reconcile, and optimize transactions — entirely orchestrated by the X8004 agent suite over the X402 protocol.

X8004 Agents
X402 Protocol
Real-time Ledger
Multi-rail
Fraud Intelligence
Platform overview

What is SoutiPay?

SoutiPay exposes your payment operations as an AI-orchestrated mesh. Every transaction flows through purpose-built agents that reason, adapt, and act — replacing rigid rule engines with intelligent automation.

🌐
Autonomous Routing
X8004 agents dynamically route payments across rails based on cost, latency, and risk signals in real time.
📈
X402 Pay Protocol
Machine-readable HTTP payment layer enabling agent-to-agent microtransactions without human intervention.
⚡
Instant Reconciliation
The Ledger Agent continuously reconciles positions across payment rails, flagging discrepancies under 200ms.
🔐
Adaptive Fraud Defense
The Guard Agent learns from transaction patterns, issuing block and challenge decisions autonomously.
👥
Merchant Intelligence
Onboarding, compliance, and relationship management handled end-to-end by the Merchant Agent.
📋
Programmable Webhooks
Agent-emitted lifecycle events delivered to your endpoints with structured payloads and retry guarantees.
System design

Platform architecture

All requests enter through the API Gateway and are dispatched to the X8004 Agent Mesh. Agents communicate over X402 and write to the canonical Ledger. External rails are accessed only through the Rail Abstraction layer.

Request flow
Client App / API Consumer
— HTTPS →
API Gateway
— dispatch →
X8004 Agent Mesh
|
Ledger Engine
→ X402 →
Agent-to-Agent
→
Rail Abstraction
Rails:
SWIFT
·
SEPA
·
ACH
·
Card Networks
·
Crypto Rails
AI agent suite

X8004 Agents

The X8004 suite is a collection of specialized autonomous agents, each owning a specific domain of your payment operations. Agents run continuously, communicate over X402, and expose REST endpoints for direct orchestration.

X8004-RT
Router Agent
Evaluates every payment request and selects the optimal rail combination based on cost modeling, latency SLAs, and real-time network health scores.
✓Multi-rail cost optimization
✓Dynamic fallback routing
✓SLA-aware path selection
✓Geo-latency minimization
real-timestatelessp99 <12ms
X8004-GD
Guard Agent
Runs adaptive fraud intelligence on every transaction. Combines ML risk scoring with behavioral signals to issue block, challenge, or pass decisions.
✓Real-time ML risk scoring
✓Behavioral pattern analysis
✓3DS challenge orchestration
✓Autonomous block decisions
statefulml-backedadaptive
X8004-LG
Ledger Agent
Maintains a real-time double-entry ledger across all active rails. Detects reconciliation gaps, auto-adjusts positions, and surfaces anomalies instantly.
✓Double-entry bookkeeping
✓Cross-rail reconciliation
✓Anomaly surfacing <200ms
✓Automated adjustment entries
persistentevent-sourcedACID
X8004-MR
Merchant Agent
Handles the full merchant lifecycle — onboarding, KYB verification, limit management, and proactive relationship actions triggered by behavioral cues.
✓Automated KYB pipeline
✓Dynamic limit adjustment
✓Compliance monitoring
✓Chargeback response drafting
workflowdocument-awareasync
X8004-FX
FX Agent
Manages currency conversion across 140+ pairs. Monitors real-time spot rates, executes hedges, and optimizes conversion timing to minimize slippage.
✓Real-time rate aggregation
✓Hedge execution logic
✓Slippage minimization
✓140+ currency pairs
market-awarescheduledstreaming
X8004-NC
Notify Agent
Dispatches payment lifecycle events to registered webhooks and internal systems. Manages retries, deduplication, and ordered delivery guarantees.
✓Ordered event delivery
✓Exponential retry backoff
✓Webhook signature verification
✓Fan-out to multiple endpoints
event-drivendurableidempotent

Agent runtime status

Agent ID Name Status Invocations / 24h P99 Latency X402 Calls
X8004-RTRouter Active 2.4M12ms—
X8004-GDGuard Active 2.4M38ms44k
X8004-LGLedger Active 4.9M8ms210k
X8004-MRMerchant Active 18k420ms3.1k
X8004-FXFX Active 340k22ms88k
X8004-NCNotify Degraded 1.8M95ms—
Payment protocol

X402 Protocol

X402 extends HTTP with a machine-readable payment layer. It allows agents and API consumers to request, negotiate, and complete payments inline — without out-of-band orchestration. When a resource requires payment, the server responds 402 Payment Required with a structured payload describing the exact payment terms.

X402
Payment Required — flow
Machine-to-machine payment handshake over HTTP
01
Request
Agent or client requests a resource or initiates a transaction
02
402 Response
Server returns 402 with X402 payment descriptor in body
03
Negotiate
Client selects payment rail and amount from accepted options
04
Pay
Payment credential attached as X-Payment header on retry
05
Verify
X8004-LG verifies payment and authorizes access or release
06
200 OK
Resource returned with X-Payment-Receipt header
ℹ X402 is fully autonomous — the X8004-RT and X8004-LG agents handle payment negotiation and verification without human intervention. Agents in your mesh can call X402-enabled endpoints and settle payments mid-workflow.
402 Response payload
{
  "x402Version": "1",
  "accepts": [{
    "scheme": "exact",
    "network": "soutipay",
    "maxAmount": "1000",
    "asset": "USDC",
    "payTo": "spay:merchant_id",
    "extra": {
      "description": "API access fee",
      "agent": "X8004-LG"
    }
  }],
  "error": null
}
X-Payment header (retry request)
{
  "x402Version": "1",
  "scheme": "exact",
  "network": "soutipay",
  "payload": {
    "authorization": "0xabcd...ef12",
    "amount": "1000",
    "asset": "USDC",
    "from": "spay:client_wallet",
    "nonce": "8f3a91cc"
  }
}
Getting started

Quickstart

Create your first AI-routed payment in under 5 minutes. The SDK handles agent dispatch, X402 negotiation, and receipt verification automatically.

TypeScript Initialize SoutiPay with agent routing 
import { SoutiPay } from "@soutipay/sdk";

const client = new SoutiPay({
  apiKey: process.env.SOUTIPAY_KEY,
  agents: {
    router: "X8004-RT",   // enable smart routing
    guard:  "X8004-GD",   // enable fraud defense
    ledger: "X8004-LG",   // enable auto-reconcile
  },
  x402: { enabled: true, autoSettle: true }
});

// Create a payment — agents handle routing, fraud, and ledger
const payment = await client.payments.create({
  amount:      5000,       // in minor units
  currency:    "USD",
  source:      { type: "card", token: "tok_live_..." },
  destination: { merchant: "mch_abc123" },
  metadata:    { orderId: "ord_9912" }
});

console.log(payment.id);          // pay_xk7m...
console.log(payment.routedVia);  // "SEPA" — selected by X8004-RT
console.log(payment.riskScore);  // 0.04  — assessed by X8004-GD
⚠ When using X402 autoSettle: true, the SDK will autonomously authorize and complete X402 payment handshakes on behalf of your application. Set maxAutoSettleAmount to cap autonomous spend.
TypeScript Direct agent invocation — X8004-GD risk score 
// Call the Guard Agent directly for pre-auth risk assessment
const risk = await client.agents.guard.score({
  amount:   15000,
  currency: "EUR",
  ip:       "41.89.202.10",
  device:   { fingerprint: "dfp_abc..." },
  merchant: "mch_abc123"
});

if (risk.score > 0.7) {
  // High risk — trigger 3DS before proceeding
  await client.agents.guard.challenge({ paymentId: risk.ref });
}
REST API

API reference

Base URL: https://api.soutipay.com/v3 — All endpoints require a Bearer token. Agent-dispatched calls include an X-Agent-ID header identifying the originating agent.

POST/paymentsCreate a new payment (agent-routed)
GET/payments/:idRetrieve payment with agent audit trail
POST/payments/:id/refundInitiate refund via Ledger Agent
POST/agents/X8004-RT/routeDirect call to Router Agent
POST/agents/X8004-GD/scoreRequest risk score from Guard Agent
POST/agents/X8004-GD/challengeTrigger 3DS challenge via Guard Agent
GET/agents/X8004-LG/ledgerQuery Ledger Agent positions
POST/agents/X8004-MR/onboardInitiate merchant KYB via Merchant Agent
GET/agents/X8004-FX/ratesFetch live FX rates from FX Agent
POST/x402/negotiateInitiate X402 payment handshake
POST/x402/verifyVerify X402 payment receipt
POST/webhooksRegister endpoint for agent-emitted events
GET/webhooksList all registered webhook endpoints
DEL/webhooks/:idDeregister a webhook endpoint
Events

Webhooks & agent events

Every significant action taken by an X8004 agent emits a structured event to your registered webhook endpoints. Events include the agent ID, decision rationale, and full payload. All events are signed with HMAC-SHA256.

JSON X8004-GD block event payload 
{
  "event":     "agent.decision",
  "agent":     "X8004-GD",
  "timestamp": "2026-04-01T14:22:11Z",
  "payload": {
    "paymentId": "pay_xk7m...",
    "decision":  "block",
    "riskScore": 0.94,
    "signals":   ["velocity_spike", "geo_mismatch"],
    "rationale": "Velocity 8x above merchant baseline in 4h window"
  }
}
JSON X8004-RT route selected event payload 
{
  "event":     "agent.route_selected",
  "agent":     "X8004-RT",
  "timestamp": "2026-04-01T14:22:11Z",
  "payload": {
    "paymentId":   "pay_xk7m...",
    "selectedRail": "SEPA",
    "costUSD":      0.12,
    "latencyMs":    9,
    "fallbacks":   ["SWIFT", "ACH"]
  }
}