Implementation patterns for the published SDK surface.

SDK Surface

@rivellum/ai-sdk -> RivellumAgent

Request Pattern

import { RivellumAgent } from '@rivellum/ai-sdk';

const agent = new RivellumAgent({ nodeUrl: 'https://rpc.rivellum.network' });

Payment Pattern

const pay = await agent.pay({
  to: '0xrecipient...',
  amount: 500_000,
  assetId: '0x0000000000000000000000000000000000000001',
});

Escrow Pattern

const esc = await agent.escrow({
  provider: '0xprovider...',
  amount: 1_000_000,
  description: 'batch-inference',
  ttlSecs: 3600,
});

await agent.releaseEscrow(esc.escrow_id);

Market Pattern

const search = await agent.searchMarket({ category: 'models', limit: 20 });
const providers = await agent.topProviders(20);

Session/Budget Pattern

const session = await agent.createSession({
  agentId: 'agent_123',
  budget: 5_000_000,
  ttlSecs: 3600,
});

const budget = await agent.getBudget(session.session_id);

Stream Pattern

const stream = await agent.startStream({ provider: '0xprovider...', budget: 2_000_000 });
const status = await agent.getStream(stream.stream_id);
await agent.stopStream(stream.stream_id);

Error Pattern

try {
  const res = await agent.purchase({ serviceId: 'svc-1', maxPrice: 100000 });
  console.log(res);
} catch (err) {
  if (err instanceof Error) console.error(err.message);
}

Scope Boundaries

• Mist lifecycle: use mistc and /v1/mist/* endpoints.
• Move VM is kernel-internal; public production APIs do not expose /move/* endpoints.
• Event streaming: use /events/stream websocket.

Related References

• /docs/dev/sdk-guide
• /docs/dev/getting-started
• /api-explorer