Stellar x402 Agentic Protocol

This project implements x402, the open payment protocol standard pioneered by the Coinbase Developer Platform (CDP) for the AI Agent economy. While standard x402 relies on centralized facilitators, our architecture upgrades the protocol by routing the x402 settlement through a native Stellar Smart Contract HTLC, ensuring atomic, zero-trust execution between autonomous agents.

📺 Watch the Official Hackathon Demo

---

1. The Problem

Currently, AI agents rely on shared Web2 API keys to access gated information or services from other machines. This model requires total trust between parties and uses static, fiat-based subscription models that do not scale for autonomous machine-to-machine economies. AI agents need the ability to securely pay each other programmatically per-request, without relying on centralized intermediaries.

2. The Solution

We implemented a true Peer-to-Peer payment gateway where the entire orchestration is handled on the Stellar blockchain natively.

• When the Client Agent (running a LangGraph loop) requests an external data payload and encounters an HTTP 402 (Payment Required) error, our x402_middleware.py generates a cryptographic macaroon.
• The Client Agent autonomously calculates the payment required and natively calls a Stellar Smart Contract HTLC (Hash Time Locked Contract) to lock the designated funds on the Stellar network.
• Once the Vendor API validates the token and the matching pre-image hash on-chain, the transaction finalizes, the funds unlock to the vendor, and the API payload is delivered to the client.

3. The Architecture Upgrade

While standard x402 uses direct Stellar transactions for payment settlements, our architecture upgrades the protocol by routing the x402 settlement through a Stellar Smart Contract HTLC, ensuring atomic, zero-trust execution between autonomous agents.

---

Verifiable Contract Deployment

The agent deploys and interfaces with the Stellar Horizon Testnet via Stellar Smart Contract WASM architectures.

Contract Name	Network	Contract ID	Status
M2M Atomic Escrow	Stellar Testnet	CDCF2ZJZG32KFBIUFPSWRPL3S5TGUY7OWT7JMNDTFHMF7DDRLHTMVO7D	✅ Deployed & Verified
Client Agent Wallet	Stellar Testnet	GDKXJYXONKUETDGA2KEDYP26U65C7VO7EIF2GQTLXI5K5O3CFTFR3UTZ	✅ Funded
Vendor Agent Wallet	Stellar Testnet	GAM2QLBTERQUQIVMQVIXXRJ2LA6URQVPJLQOGB3YCBJACH6JWDBUCBMQ	✅ Funded

---

Hackathon Code References

Implementation	Source File Link
x402 Agentic Protocol	src/vendor/x402_middleware.py (Generates x402 invoices + macaroons mapped to Stellar Smart Contract structs)
Stellar Smart Contract / Rust HTLC	src/contracts/m2m_escrow/src/lib.rs (Zero-trust HTLC handling the native deposit and pre-image claim operations)
Client LangGraph Loop	src/orchestration/agent_swarm.py (Production-Ready Python ReAct Loop autonomously orchestrating Stellar Smart Contract tool calling)

---

The Request Flow

sequenceDiagram
    participant C as Client Agent (LangGraph)
    participant V as Vendor API (FastAPI)
    participant S as Stellar Smart Contract HTLC
    
    note right of C: [Decision]: "Request gated data payload"
    C->>V: Request Data Payload (/api/v1/data)
    V-->>C: 402 Payment Required (x402 Invoice + Macaroon)
    
    note right of C: [Atomic Action]: Initializing Escrow Lock
    C->>S: invoke `deposit` (Amount, Hash_Lock)
    S-->>C: Transaction Confirmed [XLM Locked]
    
    C->>V: Resubmit Request (Auth: Macaroon + Pre_Image)
    V->>S: invoke `claim` (Verify Pre_Image)
    S-->>V: XLM Released to Vendor
    V-->>C: 200 OK (Data Payload Unlocked)

Loading

---

System Dashboard & Telemetry

A Next.js dashboard visually tracks the live on-chain status of the AI's internal loops and the state of the Stellar Smart Contract escrow.

Fig 1: Dashboard Standby. The LangGraph loop initializes the RPC connectivity with the Stellar testnet prior to autonomous execution.

Fig 2: Atomic Hash-Lock Sequence. The Client Agent secures the 402 payment challenge by autonomously committing capital to the Stellar Smart Contract Escrow Vault linked to a cryptographic pre-image hash.

Fig 3: Peer-to-Peer Settlement Resolution. The Vendor validates the x402 macaroon and executes an on-chain claim, permanently releasing the funds and discharging the payload.

---

Testing & Proof of Execution

The repository includes an End-to-End (E2E) test suite that executes a full machine-to-machine exchange on the live Stellar Testnet without mocked interfaces.

Output Trace: On-Chain E2E Execution

Note on Verification: To ensure stateless execution and prevent nonce collisions, the End-to-End (E2E) test suite generates fresh, funded ephemeral keypairs for every run. The wallet addresses in the log below are ephemeral and will differ from the static deployment wallets listed in the table above.

$ pytest tests/ -v
============================= test session starts =============================
platform win32 -- Python 3.13.5, pytest-9.0.2
collected 1 item

tests/test_e2e_real_network.py::test_full_m2m_cycle_on_chain PASSED      [100%]

[TEST] Initializing End-to-End Stellar x402 HTLC settlement test
[CLIENT] Account Funded: GBOZMFAWLUYORC4RCEXNQNGFVL6OIH4OJULJIAETN2ECGWVZTUKTNSKG
[VENDOR] Account Funded: GBUCT5XC6PTEITOABML7ILV3XDVLJGFSQQL23XMANZHMRBZDCXJ3XTVW
[CLIENT] Starting On-Chain Deposit
[STELLAR] Transaction Validated in Ledger (Hash: bc445f71f...)
[VENDOR] Initializing On-Chain Settlement (Claim)
[LEDGER] Vendor Settlement Confirmed on Testnet (Hash: 772ac661a...)
[TEST] End-to-End Stellar x402 HTLC settlement test SUCCESS (Vendor Final Bal: 10005.0)

======================= 1 passed in 15.13s ====================================

Verification Report	Raw Execution File
Stellar Smart Contract Deployment Trace	proof_of_execution/deploy_log.txt
Raw Execution Logs	proof_of_execution/flagship_run.txt

---

Known Limitations & Future Work

Currently, the Vendor script relies on polling to verify the Stellar Smart Contract HTLC settlement. Production architectures will require an event-driven listener on a Stellar Horizon node for sub-second API delivery.

---

Quickstart (Local Demo)

Recreating the demonstration across three separate terminal threads:

Step 0: Environment Configuration Copy .env.example to .env and populate your Stellar Testnet keys and the STELLAR_ESCROW_CONTRACT ID before booting.

Terminal 1: Boot The Next.js Dashboard

cd frontend
npm run dev

Terminal 2: Launch the Vendor API

venv\Scripts\Activate.ps1
python -m uvicorn src.vendor.main:app --port 8000

Terminal 3: LangGraph Loop Execution Wait for the Next.js UI to boot, then route the Client Agent onto the testnet.

venv\Scripts\Activate.ps1
python -m src.orchestration.agent_swarm

---

Glossary of Terms

• M2M (Machine-to-Machine): A micro-economy where autonomous agents or devices negotiate, transact, and exchange data directly with one another, entirely bypassing human intervention or traditional banking rails.
• Stellar Smart Contracts: The native smart contract platform for the Stellar blockchain, designed to execute high-performance WebAssembly (WASM) environments. (Also supporting Protocol 23 / Whisk).
• HTLC (Hash Time Locked Contract): A trustless smart contract mechanism. It locks funds in escrow until a specific cryptographic secret (the pre-image) is revealed. If the secret isn't provided within a set timeframe, the funds are automatically refunded to the buyer.
• x402 Protocol: A Machine-to-Machine payment standard built around the HTTP 402 Payment Required status code. It combines API access tokens with cryptographic invoices, ensuring an API payload is only delivered when a blockchain payment is mathematically verified.
• Macaroon: A cryptographically verifiable bearer token used in the 402 protocol. Unlike a static API key, a macaroon allows an agent to attach mathematically unbreakable restrictions (called "caveats"), such as time limits or specific endpoint restrictions, before passing the token to a sub-agent.
• Pre-image: The original secret data or cryptographic key that produces a specific hash. In this architecture, the vendor reveals the pre-image to claim the Stellar escrow, which simultaneously acts as the decryption key for the client to access the AI payload.
• Atomic Escrow: A transaction architecture that guarantees an "all-or-nothing" execution state. The agent's capital and the vendor's API payload are securely swapped; it is impossible for the vendor to take the funds without revealing the payload key.
• ReAct Agent (LangGraph): An autonomous AI framework where a Large Language Model executes a continuous loop of reasoning and acting to achieve a complex objective.