Package com.tnsai.payment.x402

Class X402PaymentBroker

java.lang.Object
com.tnsai.payment.x402.X402PaymentBroker
All Implemented Interfaces:
com.tnsai.payment.PaymentBroker
public final class X402PaymentBroker extends Object implements com.tnsai.payment.PaymentBroker
x402 implementation of PaymentBroker.

Two-phase contract: quote(AgentPrincipal, AgentPrincipal, Service) probes the payee's resource URL, parses the HTTP 402 response, picks a compatible PaymentRequirement, and mints a priced Quote. settle(Quote) builds an EIP-3009 transferWithAuthorization payload, signs it with the configured Wallet, and replays the original HTTP request with the signed payload in the X-PAYMENT header.

Scope of P3

  • Networks: Base mainnet + Base Sepolia (EVM family). Solana stub is in the network enum but not wired here.
  • Schemes: only "exact" (single fixed-amount transfer). The protocol's "upTo" and stream variants are out of scope.
  • Idempotency: the Quote.idempotencyKey maps deterministically to the EIP-3009 nonce; the facilitator dedups on nonce reuse and the broker surfaces a prior settlement as Settlement.AlreadySettled.

Tracked under TNS-449.

Since:
0.10.5 (TNS-449 P3)

  • Nested Class Summary

    Nested classes/interfaces inherited from interface com.tnsai.payment.PaymentBroker

    com.tnsai.payment.PaymentBroker.QuoteRejectedException

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    METADATA_HTTP_METHOD
    Service.metadata key for the HTTP method to probe with (defaults to GET).
    static final String
    METADATA_NONCE_HEX
    Service.metadata key the caller can supply to fix the nonce (test/idempotency replay).
    static final String
    METADATA_RESOURCE_URL
    Service.metadata key for the resource URL to probe.

  • Method Summary

    Modifier and Type
    Method
    Description
    static X402PaymentBroker
    create(X402Config config)
    Build a broker from config; uses a fresh SecureRandom for nonces.
    static X402PaymentBroker
    create(X402Config config, SecureRandom nonceSource)
    Build a broker with a caller-supplied SecureRandom — tests use this for determinism.
    com.tnsai.payment.Quote
    quote(com.tnsai.identity.AgentPrincipal payer, com.tnsai.identity.AgentPrincipal payee, com.tnsai.payment.Service service)
     
    com.tnsai.payment.Settlement
    settle(com.tnsai.payment.Quote quote)
     

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • METADATA_RESOURCE_URL

      public static final String METADATA_RESOURCE_URL
      Service.metadata key for the resource URL to probe.
      See Also:

    • METADATA_HTTP_METHOD

      public static final String METADATA_HTTP_METHOD
      Service.metadata key for the HTTP method to probe with (defaults to GET).
      See Also:

    • METADATA_NONCE_HEX

      public static final String METADATA_NONCE_HEX
      Service.metadata key the caller can supply to fix the nonce (test/idempotency replay).
      See Also:

  • Method Details

    • create

      public static X402PaymentBroker create(X402Config config)
      Build a broker from config; uses a fresh SecureRandom for nonces.

    • create

      public static X402PaymentBroker create(X402Config config, SecureRandom nonceSource)
      Build a broker with a caller-supplied SecureRandom — tests use this for determinism.

    • quote

      public com.tnsai.payment.Quote quote(com.tnsai.identity.AgentPrincipal payer, com.tnsai.identity.AgentPrincipal payee, com.tnsai.payment.Service service)
      Specified by:
      quote in interface com.tnsai.payment.PaymentBroker

    • settle

      public com.tnsai.payment.Settlement settle(com.tnsai.payment.Quote quote)
      Specified by:
      settle in interface com.tnsai.payment.PaymentBroker