X402 Secure Developer Guide

This guide describes the integration model for X402 Secure. The XRPL-first pattern is stable: keep the XRPL x402 Facilitator as the public payment edge, pass X402 Secure extension fields or evidence references through the normal x402 flow, let X402 Secure call Trustline internally, and enforce the resulting decision before settlement. The same risk layer is also available through SDK, paid API, and proxy paths for Base, Solana, and self-hosted deployments.

Buyer Integration

Agent developers use X402 Secure when an agent needs to purchase an x402-protected resource. The buyer flow creates or references a risk session, collects evidence such as reasoning trace or intent proof, executes the x402 payment retry, and receives the resource only after the server and facilitator accept the payment.

pip install "x402-secure[signing,otel]"

from x402_secure_client import BuyerClient, BuyerConfig, RiskClient
from x402_secure_client import OpenAITraceCollector
from x402_secure_client import store_agent_trace, execute_payment_with_tid

buyer = BuyerClient(
    BuyerConfig(
        seller_base_url="https://api.example.com",
        agent_gateway_url="https://x402-proxy.t54.ai",
        buyer_private_key="YOUR_PRIVATE_KEY",
    )
)

risk = RiskClient("https://x402-proxy.t54.ai")
session = await risk.create_session(agent_did=buyer.address, app_id="my-agent")
sid = session["sid"]

tracer = OpenAITraceCollector()

tid = await store_agent_trace(
    risk,
    sid,
    "purchase_resource",
    {"resource": "premium-feed"},
    tracer.events,
)

payment = await execute_payment_with_tid(
    buyer,
    "/api/premium-feed",
    "purchase_resource",
    {"resource": "premium-feed"},
    sid,
    tid,
)

Production integrations need meaningful trace context. A placeholder trace may pass a local smoke test, but it does not provide the evidence quality needed for underwriting, dispute review, or institutional accountability. Agent payments should carry enough context to explain why the agent acted, what resource was requested, and how the request relates to the user's or application's mandate.

Server Integration

Resource servers use X402 Secure by requiring x402 payment headers and sending the payment payload plus risk context for verification. The server returns 402 Payment Required when payment evidence is missing, then verifies and settles when the buyer retries with the payment payload.

import base64
import json
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from x402_secure_client import SellerClient

app = FastAPI()
seller = SellerClient("https://x402-proxy.t54.ai/x402")

@app.get("/api/service")
async def service(request: Request):
    payment_requirements = {
        "network": "base-sepolia",
        "maxAmountRequired": "100000",
        "asset": "0x...",
        "payTo": "0x...",
    }

    x_payment = request.headers.get("X-PAYMENT")
    x_payment_secure = request.headers.get("X-PAYMENT-SECURE")
    risk_session = request.headers.get("X-RISK-SESSION")

    if not all([x_payment, x_payment_secure, risk_session]):
        return JSONResponse({"accepts": [payment_requirements]}, status_code=402)

    result = await seller.verify_then_settle(
        json.loads(base64.b64decode(x_payment)),
        payment_requirements,
        x_payment_b64=x_payment,
        x_payment_secure=x_payment_secure,
        risk_sid=risk_session,
    )

    return JSONResponse({"ok": True, "result": result})

The server treats a Trustline deny or enforce-mode review as blocking. Product-specific review experiences can be built above this layer, but settlement does not continue when the enforcement decision says the evidence is insufficient. This is the practical point of the integration: a risk decision must be enforceable before the resource is delivered or the payment is finalized.

Headers And Evidence

X402 Secure uses a compact set of headers and evidence references.

The preferred pattern is to store large evidence payloads with Trustline-backed evidence records and pass references or hashes through headers. This avoids putting sensitive or oversized reasoning material directly into payment headers.

Policy Fields

Payment requirements or request metadata can declare policy expectations. Common policy fields include whether Verifiable Intent is required, whether verified intent is required, whether a payment mandate must be present, whether holder binding is required, whether trace evidence is required, which issuers are accepted, and whether review mode blocks settlement.

Integrations treat policy as a product contract. If a server advertises that verified intent is required, a normal x402 payment payload is not sufficient by itself. In higher-value or institution-facing workflows, policy can also express the review posture needed to support liability boundaries.

XRPL Facilitator Integration

The XRPL x402 Facilitator calls X402 Secure through authenticated service boundaries rather than exposing Trustline directly to buyers. The facilitator can create evidence sessions, upload evidence, evaluate a payment context, and record receipts after settlement attempts. X402 Secure is embedded behind the public XRPL facilitator surface, so XRPL integrations do not need a separate public XRPL risk endpoint.

The important boundary is that X402 Secure owns x402 extension semantics and rail-specific payment binding, while Trustline owns canonical evidence evaluation, risk assessment, and receipt records. Keeping this boundary clear helps integrations scale across rails without rewriting the underwriting model for every facilitator.