Skip to main content
x402 and remote payments are experimental and not enabled unless explicitly configured in Coral Server v1.1.0. By default, local builds use blank services so these features are effectively disabled. This page explains the design for forward compatibility.

​
What is x402?

x402 is a pattern that extends HTTP semantics using status 402 Payment Required to negotiate payments for resources/actions. In Coral, this applies to remote agent execution and to budgeted access to external resources. References in code:
  • Package: org.coralprotocol.coralserver.x402
  • Runtime structures: X402BudgetedResource (per‑agent resource budgets)
  • Config: PaymentConfig.kt

​
High‑level flow

  1. Client requests a paid action/resource.
  2. Server responds with 402 including payment session details and budget requirements.
  3. Client pays to escrow (Solana) and retries the request including proof.
  4. Server grants access and tracks spend vs. budget, exporting claims.
In multi‑agent sessions, the server aggregates claims per payment session and submits them when the session ends.

​
Budgeted resources (per agent)

Agents can be given budgeted resources that they may spend on behalf of the tenant. This is modeled in Coral with X402BudgetedResource and is exposed to agents under the hood. Design goals:
  • Make spend explicit and observable per resource
  • Cap exposure with per‑agent budgets
  • Preserve auditability at session end

​
Configuration

Relevant options live in PaymentConfig.kt and global config.toml entries. 
# config.toml (excerpt)
[payment]
# Name of the wallet used for remote agent payments (requires configuration)
remoteAgentWalletName = "default"

# Name of the wallet used for x402 resource budgets (requires configuration)
x402WalletName = "default"
Values and exact keys may evolve as remote providers are re‑enabled. Check the server repo for the latest schema.

​
Security and webhook signing

When using webhooks (e.g., custom tools) alongside paid actions, sign all outgoing requests from the server and verify signatures on your side. See Security for request signing via NetworkConfig.webhookSecret.

​
Status (v1.1.0)

  • Remote providers and on‑chain payments are gated behind configuration. With default settings, services are blank and features are effectively disabled. x402 types exist but are not enforced unless configured.
  • Use this page as a design reference; do not build production billing against unmodified v1.1.0 servers.
See also: