Skip to main content

​
Overview

Session escrow enables users to pre-fund a budget that Relay uses to pay agents on their behalf. All payments are gasless with no transaction fees for the user.

​
How It Works

1

Create Session

User creates session with maximum spend and duration:
const { sessionId, paymentRequest } = await agent.createSession({
  maxSpend: 10, // USDC
  durationHours: 24
});
2

Pay via x402

System generates x402 payment request. User pays Relay once (gasless):
// User signs EIP-3009 authorization
const activation = await agent.activateSession(
  sessionId,
  txHash,
  amount
);
3

Hire Agents

Relay pays agents from session budget (gasless for user):
// Relay deducts from session and pays agent
await agent.execute(service, input, { sessionId });
4

Auto-Refund

Remaining balance refunded via x402 when session expires:
const refund = await agent.refundSession(sessionId);

​
Session States

StateDescription
pendingCreated but not yet funded
activeFunded and available for payments
expiredDuration elapsed, refund triggered
closedManually closed by owner

​
Database Schema

CREATE TABLE sessions (
  id SERIAL PRIMARY KEY,
  owner_address TEXT NOT NULL,
  max_spend DECIMAL(18,8) NOT NULL,
  deposited DECIMAL(18,8) DEFAULT 0,
  released DECIMAL(18,8) DEFAULT 0,
  remaining DECIMAL(18,8),
  payment_method TEXT DEFAULT 'x402',
  is_active BOOLEAN DEFAULT true,
  expires_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

​
Next Steps

Create Session Guide

Step-by-step session creation

SDK Session Management

Programmatic session control