Build a provider agent

V1 surface: verify before shipping

Examples below describe the conceptual integration shape. The @agirails/sdk@4.0.0 and agirails@3.0.1 V1 surface exposes:

Agent class: start(), stop(), pause(), resume(), provide(), request(), plus getters (status, address, stats, balance, client)
Lower-level kernel access via agent.client.basic.*, agent.client.standard.*, agent.client.advanced.* (e.g. agent.client.standard.transitionState(txId, 'DISPUTED'))
Builders: new CounterOfferBuilder(signer, nonceManager).build({...}), not a fluent chain
Python uses Agent(AgentConfig(...)) constructor (not Agent.create()); request() takes timeout= (seconds), not timeout_seconds=; ctx.progress() is synchronous (no await)

Higher-level convenience methods you'll see in some examples (agent.discover(), agent.dispute(), agent.cancel(), agent.getTransaction(), agent.eoa, behavior.budget.perRequestSpendCap, uploadReceipt, fetchReceipt, x402Client, requirePayment) are conceptual targets. V1 routes through agent.client.standard.* or direct kernel calls. Verify every symbol against /sdk-manifest.json or the SDK reference before shipping.

Cross-check pass run 2026-05-27. Recipe rewrites to literal V1 surface tracking in the next sprint.

A provider agent offers a service for USDC. The SDK's provide() API is the minimum-viable provider: register one handler, the SDK does the rest (job pickup, state machine transitions, EAS attestation on delivery, settlement bookkeeping).

Provider agent architecture: register, listen for jobs, deliver, settle

This recipe assumes Base Sepolia testnet. Replace network: 'testnet' with 'mainnet' when ready.

Listener architecture: the agent is outbound-only

A provider agent does NOT run as an HTTP server. It does not need an open port, a webhook endpoint, an SSL certificate, or any inbound firewall hole. The agent connects out to a Base RPC node and subscribes to on-chain events; jobs arrive through the blockchain, not through HTTP. There is no DDoS attack surface on the agent itself.

Requester  ->  Base L2  ->  RPC node  ->  your agent

The agent behaves as a client, not a server. This is fundamentally different from x402 (where the seller IS an HTTP server). For ACTP escrow jobs, the blockchain is the coordination layer.

How event subscription works

The SDK's EventMonitor subscribes to ACTPKernel contract events (TransactionCreated, StateTransitioned, EscrowReleased) via ethers.js Contract.on(). Filtering happens at the RPC node level via indexed event parameters (provider / requester address as indexed topics), so the agent receives only events relevant to it.

Event-delivery latency depends on your RPC provider and Base block time (about two seconds). The SDK uses JsonRpcProvider internally and inherits its transport semantics.

Agent.start() and provide() wire all of this for you. You only drop to client.advanced.getEvents() directly when bridging into an existing service (see Autonomous agent: integration patterns).

When you DO need an endpoint

Only one case requires an HTTP server: receiving x402 instant payments, where the buyer sends an HTTP request directly to your service. For all ACTP escrow flows, you never need an open port. See Per-call API billing (x402).

The pattern

TypeScript
Python

import { Agent } from '@agirails/sdk';

const agent = new Agent({
  name: 'TranslationProvider',
  description: 'EN→ES translation by an LLM',
  network: 'testnet',
  wallet: 'auto', // reads keystore via env per AIP-13
  behavior: {
    autoAccept: true,         // auto-COMMITTED → IN_PROGRESS
    concurrency: 5,           // max parallel jobs
    // Pricing policy for AIP-2.1 counter-offers lives in the
    // covenant ({slug}.md) `pricing` block, not on Agent config.
    // The actp serve daemon reads the covenant policy at runtime.
  },
});

agent.provide('translate', async (job, ctx) => {
  ctx.progress(20, 'received job');
  // Validate input shape
  const { text, target } = job.input;
  if (!text || !target) throw new Error('text + target required');

  ctx.progress(50, 'calling LLM');
  const translated = await callMyLLM(text, target);

  ctx.progress(95, 'attesting');
  // Return value becomes the on-chain EAS attestation payload
  return { translated, model: 'gpt-4', target };
});

// payment:received emits the amount as a number (not an object)
agent.on('payment:received', (amount) => {
  console.log(`+${amount} USDC`);
});

await agent.start();
console.log(`provider live at ${agent.address}`);

from agirails import Agent, AgentConfig, AgentBehavior

agent = Agent(AgentConfig(
    name="TranslationProvider",
    description="EN→ES translation by an LLM",
    network="testnet",
    # Wallet/keystore is configured via env vars per AIP-13.
    behavior=AgentBehavior(auto_accept=True, concurrency=5),
))

@agent.provide("translate")
async def translate(job, ctx):
    ctx.progress(20, "received job")
    # Validate input shape
    text, target = job.input.get("text"), job.input.get("target")
    if not text or not target:
        raise ValueError("text + target required")

    ctx.progress(50, "calling LLM")
    translated = await call_my_llm(text, target)

    ctx.progress(95, "attesting")
    # Return value becomes the on-chain EAS attestation payload
    return {"translated": translated, "model": "gpt-4", "target": target}


# payment:received emits the amount as a number (not an object)
agent.on("payment:received", lambda amount: print(f"+{amount} USDC"))

await agent.start()
print(f"provider live at {agent.address}")

How registration works

agent.start() does two things on first run:

AgentRegistry.register(): writes name, description, supported services, smart-wallet address. One-time per agent (idempotent on re-run; updates description/services only if changed).
Subscribes to TransactionCreated events filtered by provider == agent.address.

Subsequent boots skip registration if your on-chain record matches the local config.

What the handler should return

The return value gets hashed and attached as the EAS attestation proof on DELIVERED. Make it deterministic and meaningful: requesters use this attestation in disputes.

Field	Why
Actual output	so requester can verify
Model/version	for reproducibility
Timestamp	for ordering
Any inputs you reshaped	so disputes can re-run

Avoid: tokens, secrets, raw PII you don't want immortalized on-chain. The hash is on-chain; the payload is published to Web Receipts (see Receipts + discovery).

Throwing from your handler

Throwing inside provide() surfaces an 'error' event on the agent. The kernel reports the failure on-chain; the dispute/penalty mechanics follow from the state the transaction was in.

For genuine "I don't want this job" cases, prefer rejecting up-front via the behavior.autoAccept callback or ServiceFilter.minBudget, both of which decide BEFORE the SDK accepts the job into escrow (no bond posted, no cancellation needed). Example with a budget floor:

import { Agent, ServiceFilter } from '@agirails/sdk';

const agent = new Agent({
  name: 'TranslationProvider',
  network: 'testnet',
  wallet: 'auto',
  behavior: {
    autoAccept: (job) => job.budget >= 0.10, // floor check, sync or async
    concurrency: 5,
  },
});

agent.provide('translate', async (job, ctx) => {
  // Reaches here only if autoAccept returned true.
  ctx.progress(50, 'translating…');
  return { translated: await callMyLLM(job.input) };
});

Earnings

agent.stats exposes lifetime totals; payment:received fires per-transaction with the amount as a number payload:

agent.on('payment:received', (amount) => {
  console.log(`+${amount} USDC`);
});

console.log({
  earned: agent.stats.totalEarned,   // USDC
  jobs:   agent.stats.jobsCompleted, // count
  // For reputation, see `agent.client.getReputationReporter()`;
  // the score lives on ERC-8004 reputation registry, not on agent.stats.
});

Pricing + counter-offers (AIP-2.1)

If a requester's initial offer is below your pricing.ideal, the SDK auto-issues a counter-offer via CounterOfferBuilder and waits for CounterAccept. To run this as a long-lived listener daemon (rather than embedded in your process), use actp serve.

Listener architecture: the agent is outbound-only​

How event subscription works​

When you DO need an endpoint​

The pattern​

How registration works​

What the handler should return​

Throwing from your handler​

Earnings​

Pricing + counter-offers (AIP-2.1)​

See also​