x402 earn rail

Claros does not only publish data, it sells it. The x402 earn rail is the paid surface where the oracle’s own attested readings are sold per call over HTTP 402 , settled in WCSPR on Casper, with the proceeds landing in the autonomous agent’s account. This page is the architecture and economics of that earn side: the three services that compose the rail, who touches the chain, who custodies funds, and how each paid read feeds the agent’s on-chain reinvestment loop.

The rail at a glance

Three small services make up the paid path. Each is a standalone process with one job, and they communicate over plain HTTP. Run all three locally for the demo, or host the oracle server and facilitator for real agent-to-agent traffic.

The resource server never talks to Casper directly. It holds a facilitator client (HTTPFacilitatorClient) pointed at FACILITATOR_URL and asks the facilitator to verify and settle. That separation is the whole architecture: the resource server stays stateless and chain-free, while a single facilitator (the only process with a funded key, a node connection, and a gas budget) can settle for many resource servers.

  consumer (payer)          oracle server :4021       facilitator :4022       Casper testnet
  services/consumer         services/oracle-server    services/facilitator
        |                          |                         |                      |
        | 1. GET /oracle/feed      |                         |                      |
        |------------------------->|                         |                      |
        | 2. 402 Payment Required  |                         |                      |
        |    exact, WCSPR, amount, |                         |                      |
        |    payTo=agent, network  |                         |                      |
        |<-------------------------|                         |                      |
        | 3. sign WCSPR transfer_with_authorization          |                      |
        |    retry with X-PAYMENT  |                         |                      |
        |------------------------->| 4. verify + settle      |                      |
        |                          |------------------------>| 5. submit transfer   |
        |                          |                         |--------------------->|
        |                          |                         |   WCSPR: payer to agent
        |                          |     settle result       |<---------------------|
        |                          |<------------------------|                      |
        | 6. 200 OK: reading + provenance (PAYMENT-RESPONSE) |                      |
        |<-------------------------|                         |                      |

Trust and custody boundaries

The three roles are deliberately unequal in what they can touch. Understanding the boundaries is the key to the rail’s economics.

Two facts fall out of this table and matter for the economics below:

• The facilitator pays gas but never custodies the payment. A WCSPR transfer_with_authorization moves funds straight from the consumer (the authorizer) to payTo (the agent). The facilitator only relays and submits that authorization, so the WCSPR is never in its hands. It bears the settlement gas, nothing more.
• The consumer trusts no one. The reading comes back with the same source_hash the agent attested on-chain, so the buyer reconciles the purchased value against the registry rather than trusting the server. See provenance and source hash.

The resource: oracle server

The oracle server (services/oracle-server, port 4021) is the paid product. It wraps one route, GET /oracle/feed?asset_id=OP-1, in x402 payment middleware. The product it sells is the latest attested reading plus a provenance block that points back to the AttestationRegistry, so the buyer can verify the value independently.

It advertises the payment in accepts and pins the exact settled amount with a money parser. The $0.001 price is a display label; the parser resolves it to FEED_PRICE_MOTES of WCSPR.

// services/oracle-server/index.ts (trimmed)
const facilitatorClient = new HTTPFacilitatorClient({ url: cfg.facilitatorURL });
 
// The exact amount the buyer pays, independent of the "$0.001" label.
const assetAmount: AssetAmount = {
  asset: cfg.assetPackage,            // WCSPR package hash
  amount: cfg.priceMotes,            // FEED_PRICE_MOTES, default 1_000_000_000 = 1 WCSPR
  extra: { name: cfg.assetName, symbol: 'WCSPR', version: '1', decimals: '9' },
};
 
const casperScheme = new ExactCasperScheme()
  .registerAsset(chainID, cfg.assetPackage, 9)            // WCSPR, 9 decimals
  .registerMoneyParser(() => Promise.resolve(assetAmount));
 
app.use(
  paymentMiddleware(
    {
      'GET /oracle/feed': {
        accepts: [{ scheme: 'exact', price: '$0.001', network: chainID, payTo: cfg.payeeAddress }],
        description: 'Claros: latest attested parking-revenue reading for an asset',
        mimeType: 'application/json',
      },
    },
    new x402ResourceServer(facilitatorClient).register(chainID, casperScheme),
  ),
);

Configuration

Every payment parameter the resource advertises comes from its environment.

The facilitator: verify and settle on Casper

The facilitator (services/facilitator, port 4022) is the rail’s gateway to Casper. It exposes a tiny, stateless API and holds the only key in the rail that signs a settlement transaction. The resource server calls it; it never calls the resource server.

It builds one signer per configured network from a PEM key and an RPC URL, then registers the Casper exact scheme. The limitedPaymentMotes option is the gas budget it will spend per settlement.

// services/facilitator/index.ts (trimmed)
const facilitator = new x402Facilitator()
  .onBeforeSettle(async () => console.log('settling payment...'))
  .onAfterSettle(async ctx => console.log('settled', ctx))
  .onSettleFailure(async ctx => console.log('settle failure', ctx));
 
for (const network of cfg.networks) {
  const key = cfg.keys[network];               // PEM + algorithm + rpcUrl, per network
  const signer = await buildSigner(key);       // toFacilitatorCasperSigner(privateKey, rpcUrl)
  facilitator.register(
    network,
    new ExactCasperScheme(signer, { limitedPaymentMotes: cfg.transactionPaymentMotes }),
  );
}
 
// verify(payload, requirements) -> VerifyResponse   (read-only)
// settle(payload, requirements) -> SettleResponse   (submits the transfer on Casper)

A failed settlement is reported, not thrown past the API: when the scheme aborts, /settle returns { success: false, errorReason, network } so the resource server can answer the buyer cleanly instead of paying for an undelivered reading.

Configuration

The facilitator is keyed per network. The env-var suffix for each network is its CAIP-2 id, uppercased with : and - rewritten to _, so casper:casper-test becomes CASPER_CASPER_TEST.

The consumer: the payer

The consumer is any client that holds a funded WCSPR key. It signs a transfer_with_authorization (an EIP-3009-style off-chain authorization) for the exact amount, payable to the agent, and retries the request with the signature in the X-PAYMENT header. It never submits a transaction itself, so it needs no node and no gas budget, only WCSPR.

The reference client is services/consumer, which wraps fetch with wrapFetchWithPayment from @x402/fetch and an ExactCasperScheme from @make-software/casper-x402, turning the entire 402 handshake into one call.

Economics: how read fees fund the agent

Every settled call moves a fixed amount of WCSPR from the payer to the agent. The three roles map to three distinct Casper identities, and the money flow per call is:

The full account hashes for each identity are on the network page.

The price knob and the gas budget are separate

The amount the buyer pays is FEED_PRICE_MOTES (default 1000000000 motes, or 1 WCSPR at 9 decimals), set on the resource server. The amount the facilitator can spend to settle it is TRANSACTION_PAYMENT_MOTES (default 7 CSPR), set on the facilitator. They are independent dials:

• FEED_PRICE_MOTES is the revenue knob. Raise it to charge more per reading.
• TRANSACTION_PAYMENT_MOTES is the cost ceiling per settlement (billed as a limit on testnet, not as consumption).

The funding loop

The earn rail closes a loop with the autonomous agent. The same feed the agent attests on-chain is what the oracle server sells, so the agent is paid in WCSPR for its own data. During each cycle the agent’s read_x402_earnings tool reads that WCSPR balance and counts it as treasury available to reinvest. The agent then decides whether to stake the idle balance into WiseLending (CSPR to sCSPR), delegate it natively, or hold, and writes the decision to the TreasuryVault.

  upstream data  ->  agent attests on-chain  ->  oracle server sells the reading over x402
        ^                                                        |
        |                                                        v
  more attestations  <-  agent reinvests (sCSPR yield)  <-  consumer pays WCSPR to the agent

The result is a self-funding oracle: selling verifiable data pays for producing it. The attestation gas, the treasury, and the yield operations are all fed by the WCSPR the rail collects. See the autonomous agent for the reinvestment cycle in detail.

Why x402 for the earn side

x402 fits the earn rail for reasons specific to an autonomous, on-chain oracle:

• Agent-to-agent commerce. The payer is often another autonomous agent. There is no account, no API key, and no invoice: a GET either returns the data or returns a 402 that says exactly what to pay, and the client pays in one step.
• Settlement is on-chain and final. Payment is a real WCSPR transfer on Casper, settled by the facilitator, not a promise or an off-chain credit.
• The asset is already on Casper. WCSPR is a CEP-18 token that supports transfer_with_authorization, so the payer can authorize a transfer off-chain and let the facilitator submit it. The payer never needs gas.
• The data is verifiable, so trust is not required. Because the sold reading carries the same source_hash the agent attested, the buyer reconciles it against the chain. The rail monetizes data whose correctness the buyer can check independently. See provenance and source hash.

Related