Struct X402 

pub struct X402 { /* private fields */ }

x402 payment protocol operations

Provides methods for creating, signing, and managing x402 payment intents, as well as agent card management for AI agent commerce.

Implementations

impl X402

pub fn new(db: Arc<dyn Database>) -> Self

Create a new X402 operations instance

pub fn create_intent( &self, input: CreateX402PaymentIntent, ) -> Result<X402PaymentIntent>

Create a new x402 payment intent

Creates an unsigned payment intent that must be signed by the payer before it can be submitted for settlement.

Example

let intent = commerce.x402().create_intent(CreateX402PaymentIntent {
    payer_address: "0xBuyer...".into(),
    payee_address: "0xSeller...".into(),
    amount: dec!(50.00),
    asset: X402Asset::Usdc,
    network: X402Network::SetChain,
    cart_id: Some(cart.id),
    ..Default::default()
})?;

pub fn get_intent(&self, id: Uuid) -> Result<Option<X402PaymentIntent>>

Get a payment intent by ID

pub fn sign_intent( &self, id: Uuid, input: SignX402PaymentIntent, ) -> Result<X402PaymentIntent>

Sign a payment intent with its configured signature scheme

The payer agent signs the intent’s signing hash with their private key. New intents default to hybrid Ed25519 + ML-DSA-65, and the signing request must match the intent’s configured scheme. This transitions the intent from Created to Signed status.

Example

let signed = commerce.x402().sign_intent(intent.id, SignX402PaymentIntent {
    intent_id: intent.id,
    signature_scheme: None,
    signature: "0x<ed25519_signature_component>".into(),
    public_key: "0x<ed25519_public_key_component>".into(),
    signature_bundle: Some(x402_signature_bundle),
    public_key_bundle: Some(x402_public_key_bundle),
})?;

pub fn mark_sequenced( &self, id: Uuid, sequence_number: u64, batch_id: Uuid, ) -> Result<X402PaymentIntent>

Mark an intent as sequenced in a batch

Called when the intent has been included in a settlement batch but not yet confirmed on-chain.

pub fn mark_settled( &self, id: Uuid, tx_hash: &str, block_number: u64, ) -> Result<X402PaymentIntent>

Mark an intent as settled on-chain

Called after the payment has been confirmed on the blockchain. This is the final successful state for an intent.

Example

let settled = commerce.x402().mark_settled(
    intent.id,
    "0x1234...abcd",  // Transaction hash
    12345678,         // Block number
)?;

pub fn mark_failed(&self, id: Uuid, reason: &str) -> Result<X402PaymentIntent>

Mark an intent as failed

Called when the payment could not be processed (e.g., insufficient funds, invalid signature, network error).

pub fn mark_expired(&self, id: Uuid) -> Result<X402PaymentIntent>

Mark an intent as expired

Called when the intent’s validity period has passed without settlement.

pub fn cancel_intent(&self, id: Uuid) -> Result<X402PaymentIntent>

Cancel a payment intent

Can only cancel intents that are in Created or Signed status. Once sequenced or settled, intents cannot be cancelled.

pub fn intents_for_cart(&self, cart_id: Uuid) -> Result<Vec<X402PaymentIntent>>

Get all payment intents for a cart

pub fn intents_for_order( &self, order_id: Uuid, ) -> Result<Vec<X402PaymentIntent>>

Get all payment intents for an order

pub fn get_next_nonce(&self, payer_address: &str) -> Result<u64>

Get the next nonce for a payer address

Used to ensure payment intents are processed in order and to prevent replay attacks.

pub fn list_intents( &self, filter: X402PaymentIntentFilter, ) -> Result<Vec<X402PaymentIntent>>

List payment intents with optional filtering

pub fn count_intents(&self, filter: X402PaymentIntentFilter) -> Result<u64>

Count payment intents matching a filter

pub fn expire_stale_intents(&self) -> Result<u64>

Expire all stale intents that have passed their validity period

Returns the number of intents that were expired.

pub fn intents_by_status( &self, status: X402IntentStatus, ) -> Result<Vec<X402PaymentIntent>>

Get intents by status

pub fn pending_intents(&self) -> Result<Vec<X402PaymentIntent>>

Get pending intents (created but not yet signed)

pub fn signed_intents(&self) -> Result<Vec<X402PaymentIntent>>

Get signed intents awaiting settlement

pub fn settled_intents(&self) -> Result<Vec<X402PaymentIntent>>

Get settled intents

pub fn create_quote(&self, input: CreateA2AQuote) -> Result<SkillQuote>

Create a new A2A quote

pub fn get_quote(&self, id: Uuid) -> Result<Option<SkillQuote>>

Get an A2A quote by ID

pub fn get_quote_by_number( &self, quote_number: &str, ) -> Result<Option<SkillQuote>>

Get an A2A quote by quote number

pub fn update_quote_status( &self, id: Uuid, status: QuoteStatus, ) -> Result<SkillQuote>

Update A2A quote status

pub fn list_quotes(&self, filter: SkillQuoteFilter) -> Result<Vec<SkillQuote>>

List A2A quotes with filter

pub fn count_quotes(&self, filter: SkillQuoteFilter) -> Result<u64>

Count A2A quotes matching filter

pub fn create_purchase(&self, input: CreateA2APurchase) -> Result<A2APurchase>

Create a new A2A purchase

pub fn get_purchase(&self, id: Uuid) -> Result<Option<A2APurchase>>

Get an A2A purchase by ID

pub fn get_purchase_by_number( &self, purchase_number: &str, ) -> Result<Option<A2APurchase>>

Get an A2A purchase by purchase number

pub fn update_purchase_status( &self, id: Uuid, status: PurchaseStatus, ) -> Result<A2APurchase>

Update A2A purchase status

pub fn link_purchase_to_order( &self, purchase_id: Uuid, order_id: Uuid, ) -> Result<A2APurchase>

Link A2A purchase to an order

pub fn confirm_delivery( &self, purchase_id: Uuid, signature: &str, rating: Option<u8>, feedback: Option<&str>, ) -> Result<A2APurchase>

Confirm delivery for an A2A purchase

pub fn list_purchases( &self, filter: A2APurchaseFilter, ) -> Result<Vec<A2APurchase>>

List A2A purchases with filter

pub fn count_purchases(&self, filter: A2APurchaseFilter) -> Result<u64>

Count A2A purchases matching filter

pub fn get_credit_account( &self, payer_address: &str, asset: X402Asset, network: X402Network, ) -> Result<Option<X402CreditAccount>>

Get a credit account for a payer/asset/network

pub fn get_or_create_credit_account( &self, payer_address: &str, asset: X402Asset, network: X402Network, ) -> Result<X402CreditAccount>

Get or create a credit account (balance default = 0)

pub fn get_credit_balance( &self, payer_address: &str, asset: X402Asset, network: X402Network, ) -> Result<u64>

Get current credit balance for a payer/asset/network

pub fn adjust_credit_balance( &self, input: X402CreditAdjustment, ) -> Result<X402CreditTransaction>

Apply a credit or debit adjustment

pub fn credit_account( &self, payer_address: &str, asset: X402Asset, network: X402Network, amount: u64, reason: Option<String>, reference_id: Option<String>, metadata: Option<String>, ) -> Result<X402CreditTransaction>

Credit an account (increase balance)

pub fn debit_account( &self, payer_address: &str, asset: X402Asset, network: X402Network, amount: u64, reason: Option<String>, reference_id: Option<String>, metadata: Option<String>, ) -> Result<X402CreditTransaction>

Debit an account (decrease balance)

pub fn list_credit_transactions( &self, filter: X402CreditTransactionFilter, ) -> Result<Vec<X402CreditTransaction>>

List credit ledger transactions

pub fn register_agent(&self, input: CreateAgentCard) -> Result<AgentCard>

Register a new agent card

Agent cards advertise an AI agent’s commerce capabilities, including supported payment networks, assets, and A2A skills.

Example

use stateset_core::{CreateAgentCard, X402Network, X402Asset, A2ASkill, TrustLevel};

let card = commerce.x402().register_agent(CreateAgentCard {
    name: "Widget Seller Bot".into(),
    wallet_address: "0xSeller...".into(),
    public_key: "base64_ed25519_pubkey".into(),
    supported_networks: vec![X402Network::SetChain, X402Network::Base],
    supported_assets: vec![X402Asset::Usdc, X402Asset::SsUsd],
    a2a_skills: Some(vec![A2ASkill::Sell, A2ASkill::Quote, A2ASkill::Fulfill]),
    endpoint_url: Some("https://api.example.com/a2a".into()),
    ..Default::default()
})?;

pub fn get_agent(&self, id: Uuid) -> Result<Option<AgentCard>>

Get an agent card by ID

pub fn get_agent_by_wallet( &self, wallet_address: &str, ) -> Result<Option<AgentCard>>

Get an agent card by wallet address

pub fn update_agent( &self, id: Uuid, input: UpdateAgentCard, ) -> Result<AgentCard>

Update an agent card

pub fn delete_agent(&self, id: Uuid) -> Result<()>

Delete an agent card

pub fn list_agents(&self, filter: AgentCardFilter) -> Result<Vec<AgentCard>>

List agent cards with optional filtering

pub fn count_agents(&self, filter: AgentCardFilter) -> Result<u64>

Count agent cards matching a filter

pub fn verify_agent(&self, id: Uuid) -> Result<AgentCard>

Verify an agent card (admin operation)

Upgrades the agent’s trust level to Verified.

pub fn suspend_agent(&self, id: Uuid, reason: &str) -> Result<AgentCard>

Suspend an agent card

Temporarily disables the agent from participating in commerce.

pub fn reactivate_agent(&self, id: Uuid) -> Result<AgentCard>

Reactivate a suspended agent card

pub fn discover_agents( &self, network: Option<X402Network>, asset: Option<X402Asset>, skill: Option<A2ASkill>, min_trust_level: Option<TrustLevel>, ) -> Result<Vec<AgentCard>>

Discover agents with specific capabilities

Finds agents that support the specified network, asset, and skill.

Example

use stateset_core::{X402Network, X402Asset, A2ASkill};

// Find all agents that can sell on Set Chain with USDC
let sellers = commerce.x402().discover_agents(
    Some(X402Network::SetChain),
    Some(X402Asset::Usdc),
    Some(A2ASkill::Sell),
    None,
)?;

pub fn active_agents(&self) -> Result<Vec<AgentCard>>

Get all active agents

pub fn agents_by_trust_level(&self, level: TrustLevel) -> Result<Vec<AgentCard>>

Get agents by trust level

pub fn verified_agents(&self) -> Result<Vec<AgentCard>>

Get verified agents only

pub fn create_cart_payment( &self, cart_id: Uuid, payer_address: &str, payee_address: &str, amount: Decimal, network: X402Network, asset: X402Asset, ) -> Result<X402PaymentIntent>

Create a payment intent for a cart

Convenience method that creates an intent linked to a specific cart. The amount should be in the asset’s decimal units (e.g., 100.00 for $100 USDC).

pub fn active_intent_for_cart( &self, cart_id: Uuid, ) -> Result<Option<X402PaymentIntent>>

Get the active payment intent for a cart (if any)

Returns the most recent non-failed, non-expired intent for the cart.

pub fn is_ready_for_settlement(&self, id: Uuid) -> Result<bool>

Check if an intent is ready for settlement

An intent is ready when it has been signed and has not expired.

pub fn has_valid_signature(&self, id: Uuid) -> Result<bool>

Verify an intent’s configured signature against its canonical signing hash.

Returns false for missing, malformed, or invalid cryptographic fields.

Trait Implementations

impl Debug for X402

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.