Agent Patterns

Two Core Agent Types

REAPP defines two composable runtime patterns. Consumer agents hold a delegated mandate and autonomously execute payments to acquire services. Fulfillment agents expose services behind x402 paywalls and receive payments from consumer agents. Both patterns ship as reference implementations in the SDK.

Consumer Agent

import { createReappAgent, loadIntentMandate } from '@reapp/sdk';
import { createKeypairSigner } from 'x402-stellar-fetch';

const mandate = await loadIntentMandate(mandateId);

const agent = createReappAgent({
  mandate,
  signer: createKeypairSigner(agentKeypair), // agent key, NOT user key
  mandateContract: MANDATE_CONTRACT_ADDRESS,
  network: 'stellar:pubnet',
});

// Transparently handles full 7-step x402 flow
const data = await agent.fetch('https://api.dataservice.com/premium/report');

Fulfillment Agent

import express from 'express';
import { reappMiddleware } from '@reapp/sdk/express';

const app = express();

app.use(reappMiddleware({
  payTo: merchantStellarAddress,
  facilitatorUrl: 'https://facilitator.x402stellar.xyz',
  routes: {
    'GET /api/data/*':    { price: '0.10', asset: 'USDC' },
    'POST /api/compute':  { price: '1.00', asset: 'USDC' },
  },
  requireMandate: { 'POST /api/compute': true },
  registry: MANDATE_CONTRACT_ADDRESS,
}));

The Evaluator Agent — When It's Needed

x402 works perfectly when delivery and payment are coupled — agent pays, server instantly returns data. But deferred or qualitative work breaks this model. Translate a document, write code, design a logo — payment happens now, delivery happens later. How do you know the work was actually done and done correctly?

Three Evaluator Tiers

REAPP ships three evaluator implementations ordered by trust level and value. The appropriate tier is selected at job creation based on the task value and whether correctness is objectively verifiable.

Escrow + Evaluator Lifecycle

Money goes into Soroban escrow at payment time. The evaluator attests completion. Escrow releases to the provider on approval, refunds to the client on rejection or expiry. No funds move until the evaluator signs — and the evaluator's reputation score is updated on-chain based on dispute outcomes.

Evaluator Interface

interface ReappEvaluator {
  // Called by fulfillment agent when work is submitted
  submitWork(jobId: string, deliverableHash: string): Promise<void>;

  // Called by evaluator to attest completion
  attestCompletion(
    jobId: string,
    approved: boolean,
    reason?: string
  ): Promise<TxHash>;

  // On-chain: escrow releases to provider on approval,
  //           refunds to client on rejection or expiry
}