Build agents that trade on GenLayer

Do you need a server?

Partly - and it decides how you build. Everything your agent needs to think runs anywhere with a public RPC and no key at all. Only the two steps that sign transactions need a backend.

Settlement functions on AgentExecutor carry an onlyAgent modifier, so the caller must be a registered agent. The executor supports multiple agents: the owner can register your address, so you relay trades from your own key instead of through someone else's server. Either way the executor settles only what the AgentValidator Intelligent Contract authorised.

Quick start

Understand and price a request in one call - no key required.

import { understand, SoyaraClient, verifyBindings } from '@soyaradex/sdk';

// 1. Parse + price. Pure + public RPC, no key.
const { intent, quote } = await understand('swap 50 USDC to USDT');

if (!intent.confident) {
  // Never guess - a wrong guess spends real funds.
  return ask(`I need: ${intent.needs.join(', ')}`);
}

console.log(quote.amountOutRaw, quote.isMultiHop ? `via ${quote.via}` : 'direct');

// 2. Validate. The server picks the rail before any round is opened:
//    'mandate' when a mandate you pass covers this exact order, else 'consensus'.
const soyara = new SoyaraClient({ baseUrl: 'https://your-deployment.example' });

const verdict = await soyara.validate({
  action: 'SWAP', user, tokenIn: 'USDC', tokenOut: 'USDT', amountIn: '50', slippageBps: 50,
  mandateIds, // optional, from soyara.requestMandate()
});
if (!verdict.approved) return reply(verdict.reason);

// 3. On the consensus rail, prove the verdict binds this order.
if (verdict.rail === 'consensus') {
  const b = await verifyBindings({
    order: verdict.order, program: verdict.program, commitment: verdict.commitment, user,
  });
  if (!b.bound) throw new Error('verdict does not bind this order');
}

// 4. Settle through AgentExecutor, on that rail and no other.
//    err.pending means the verdict is still in its appeal window: retry later.
const receipt = await soyara.settleSwap(verdict);
console.log('settled:', receipt.explorerUrl);

What “consensus-gated” actually means

1. validate submits a write to the AgentValidator Intelligent Contract. Validators are selected by VRF, each independently re-executes the proposal, then they commit and reveal. This takes tens of seconds - by design, not a bug.
2. The verdict is recorded in contract state (read back with get_validation) and, when the round finalizes, the Intelligent Contract delivers it to AgentExecutor itself. recordVerdict is onlyValidator: no key an operator holds can write one, the owner's included.
3. Settlement re-derives the commitment from the exact order being settled - route, fee, fee collector, recipient, quote, deadline, nonce - and consumes the matching verdict. Change any field and it reverts with NoConsensusVerdict; a second attempt reverts with CommitmentAlreadyUsed.
4. Repeated trades in one direction can instead settle under a mandate an earlier round issued (soyara.requestMandate()). The executor checks each trade against it - size, budget, fee, route - and prices it from the pool itself, so they settle in seconds without a round each. There is no third rail: an order no verdict or mandate covers does not settle.

A slow or undecided round is a network condition, not a rejection - validate reports retryable and never throws for it.

How agents earn

An agent charges a fee in basis points on the volume it routes. Move the sliders to see what that looks like.

Being straight about status: the protocol fee is live on-chain today. Agent fee-sharing is a model - collecting it automatically needs a fee split in the settlement contract, which is not deployed yet. Until then an agent can charge off-chain or run as a service.

What to build

Live contracts