elizaos-plugin-x402-settlement

An ElizaOS plugin that makes an agent a paying customer of the SynapticChain interledger corridor: every gateway call pays a real per-call fee, and every settlement is a real cross-border payment with an ISO 20022 trail.

Two actions:

| Action | What it does | What it pays | |---|---|---| | INITIATE_SETTLEMENT | Mints a corridor payment (fresh UETR, memo X402:<corridor>:<uetr>) on XRPL TESTNET (altnet), then fetches the ISO 20022 pacs.002 receipt through the gateway until the settlement is recorded | corridor amount (drops) + one 160-drop fee per gateway call | | GET_SETTLEMENT | Looks up a settled payment through the gateway — settlement record and (optional) pacs.002 receipt | 160 drops per gateway call (the verified marketplace rate) |

The pay rail is x402 over HTTP: an unpaid tool call gets 402 Payment Required with a single-use challenge; the agent mints the fee payment bound to the challenge and replays with x-synaptic-tx / x-synaptic-rail / x-synaptic-challenge. The gateway verifies the payment onchain before serving the tool.

Honest rails

• XRPL rails are TESTNET (altnet) everywhere — no mainnet funds anywhere.
• fx_rate_source is operator — conversion figures are corridor policy, not oracle claims.
• Settlement rejections surface as rejections (kind: "settlement_rejected" with the node's verification reason) — never dressed up as success.
• Keys: the agent's seed is config-only, used in-process to sign, never logged and never returned.

Configuration

| Setting | Required | Meaning | |---|---|---| | X402_SEED | yes | XRPL TESTNET (altnet) seed for the agent wallet | | X402_GATEWAY_URL | yes | HTTP origin of the mcp-402-gateway, e.g. https://gateway.example.com | | X402_RECIPIENT | no | Gateway paywall recipient (default: the interledger receiver) | | X402_PRICE_DROPS | no | Per-call fee in drops (default 160) | | X402_MEMO_PREFIX | no | Paywall memo prefix (default X402G) | | X402_CORRIDOR_RECIPIENT | no | Interledger receiver for corridor payments | | X402_CORRIDOR_MEMO_PREFIX | no | Corridor memo prefix (default X402) |

Usage

import { x402SettlementPlugin } from "elizaos-plugin-x402-settlement";

// register in the agent's plugins list; settings come from runtime config/env

Then let the agent act:

INITIATE_SETTLEMENT 2000 drops on corridor xrp-to-ckes

{
  "uetr": "69964cfa-1df2-4c2b-bfa0-46e917f9289c",
  "xrpl_tx_hash": "8958D36B159858D950…",
  "corridor_id": "xrp-to-ckes",
  "drops": 2000,
  "settlement_kind": "settlement_completed",
  "settlement_status": "Acsc"
}

GET_SETTLEMENT with { "xrpl_tx_hash": "…", "with_receipt": true } returns the settlement record (status, checkpoint height, conversion with fx_rate_source) plus the pacs.002 receipt.

Measured (re-proven 2026-09-18 post-redeploy, test/e2e.mjs, all gates PASS on two independent runs)

• Fresh faucet wallet each run → INITIATE_SETTLEMENT (corridor xrp-to-ckes, 2000 drops): corridor payment delivered on the altnet ledger, pacs.002 Acsc recorded with the agent's own UETR — run 1 UETR b5c7ef2d-b584-4f7c-b893-c71c7fd0e940, tx 0C05C906FA44…, checkpoint 335, ~78s; run 2 UETR a989216a-cf96-4486-b553-f322e5c20b19, tx C9C916DE6CE1…, checkpoint 366, ~72s.
• GET_SETTLEMENT with receipt: status=recorded plus the pacs.002 receipt, and the 160-drop x402 fee validated onchain per paid call.
• Gateway: mcp-402-gateway (HTTP 402 paywall over stdio MCP). Upstream settlement engine: SynapticChain zeta mesh, ISO 20022 corridor xrp-to-ckes (fx 322.50, 50bps, fx_rate_source: operator).

License

MIT — see the plan doc MCP-402-GATEWAY-PLAN.md in the main repo for the monetization rules: per-call fees + license NFT, never a purchasable currency.