SDK Installation & Setup
Terminal initialization and basic environment requirements.
npm install
Prerequisites
Node.js v18.0.0 or higher TypeScript v4.5 or higher Supabase Project Credentials
Environment Variables
NEXT_PUBLIC_FOB_API_URL=https://api.fob.io
NEXT_PUBLIC_SUPABASE_URL=https://xyz.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGc...
Authentication Module
FOB leverages Supabase Auth for high-security JWT management and Role-Based Access Control (RBAC).
// Login with identity provider
const { data, error } = await supabase.auth.signInWithPassword({
email: 'admin@entity.ai',
password: '********'
});
// Set SDK token for future requests
fob.setToken(data.session.access_token);
Token Refresh Strategy
Tokens expire every 3600s. The SDK automatically listens for session updates via Supabase broadcast.
if (session) fob.setToken(session.access_token);
});
RBAC Scopes
Type Definitions
Interface: Agent
id: string;
name: string;
status: AgentStatus;
wallet: string;
reputation: number;
credentials: Credential[];
}
Interface: Mandate
id: string;
agentId: string;
limits: SpendingLimits;
whitelist: string[];
expiresAt: string;
}
Client Initialization
The FobClient is the entry point for all protocol interactions.
const fob = new FobClient({
apiUrl: process.env.FOB_API_URL,
timeout: 10000, // 10s
retries: 3,
cache: { enabled: true, ttl: 60000 }
});
// Hook into request lifecycle
fob.interceptors.request.use((config) => {
console.log(`Outgoing: ${config.method} ${config.url}`);
return config;
});
Core Endpoints
4 EndpointsgetDashboardStats()
Returns global network metrics and aggregate system health.
getHealth()
Checks heartbeat of core settlement engine and DB connectivity.
Agents Endpoints
6 EndpointsOnboards a new autonomous agent to the protocol with DID registration.
name: "Bot-771",
wallet: "0x..."
});
Fetches complete agent profile including reputation and credentials.
Real-World Implementation
Step-by-step logic for the agentic economy.
Create Spending Mandate
Initialize a programmable spending rule. This example sets a monthly cap of 5000 USDC with a specific domain whitelist for travel bookings.
agentId: 'agt_991',
name: 'Q1 Travel Budget',
limits: {
monthly: 5000,
currency: 'USDC'
},
whitelist: ['marriott.com', 'united.com'],
expiresAt: '2026-03-31T23:59:59Z'
});
Execute Payment
Settlement via the x402 protocol. This call validates the mandate status and executes the on-chain transfer on the BASE network.
const payment = await fob.executePayment({
mandateId: mandate.id,
amount: 284.50,
merchant: 'Marriott Paris'
});
console.log(`Tx Hash: ${payment.hash}`);
} catch (err) {
if (err.code === 'MANDATE_EXCEEDED') {
// Handle over-budget scenario
}
}
Error Handling
| Error Code | Description | Recommended Action |
|---|---|---|
| AUTH_EXPIRED | JWT session has reached expiry. | Call fob.refreshToken() or re-login. |
| MANDATE_INVALID | Mandate ID not found or expired. | Check mandate validity window. |
| RATE_LIMITED | IP exceeded 100 req/sec limit. | Implement exponential backoff retry. |
| INSUFFICIENT_STAKE | Agent requires higher reputation stake. | Deposit USDC to agent staking contract. |
Deployment Configs
package.json
"name": "@fob-framework/sdk",
"version": "2.4.0",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"scripts": {
"build": "tsc",
"test": "jest"
},
"dependencies": {
"axios": "^1.6.0",
"@supabase/supabase-js": "^2.38.0"
}
}
tsconfig.json
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS",
"strict": true,
"declaration": true,
"outDir": "./dist",
"esModuleInterop": true
}
}