Usage Guide

This guide shows how to integrate Runtimee into your autonomous system or AI agent.

Installation

Install the SDK package:

npm install @runtimee/sdk
# or
pnpm add @runtimee/sdk

Basic Usage

Initialize the SDK with your API key:

import { Runtimee } from "@runtimee/sdk"

const rt = new Runtimee({
  apiKey: process.env.RUNTIMEE_API_KEY,
  // Optional: customize the API endpoint
  baseUrl: "https://api.runtimee.dev"
})

Creating an Actor

Create a financial actor with a budget and policies:

const actor = await rt.actors.create({
  name: "payment-agent",
  budget: {
    amount: "1000", // 1000 USDC
    currency: "USDC",
    period: "monthly"
  },
  policies: [
    {
      type: "allowlist",
      config: {
        allowedTargets: ["openai:gpt-4-turbo", "github:copilot"]
      }
    },
    {
      type: "max-per-call",
      config: {
        maxAmount: "50" // 50 USDC max per transaction
      }
    }
  ]
})

console.log(`Created actor ${actor.id} with name ${actor.name}`)

Making Payments

Once you have an actor, you can make payments:

const execution = await rt.actors.pay(actor.id, {
  target: "openai:gpt-4-turbo",
  amount: "5", // 5 USDC
  purpose: {
    type: "llm-inference",
    id: "chat-completion-001",
    description: "GPT-4 Turbo completion for user query"
  }
})

if (execution.status === "confirmed") {
  console.log(`Payment successful! Transaction: ${execution.txHash}`)
} else {
  console.log(`Payment failed: ${execution.status}`)
}

Previewing Payments

Before making a payment, you can preview whether it would be approved:

const { decision, policyResults } = await rt.actors.previewPay(actor.id, {
  target: "openai:gpt-4-turbo",
  amount: "5",
  purpose: {
    type: "llm-inference",
    id: "preview-001"
  }
})

switch (decision) {
  case "approved":
    console.log("Payment would be approved")
    break
  case "denied":
    console.log("Payment would be denied by policy")
    console.log("Policy results:", policyResults)
    break
  case "pending-review":
    console.log("Payment requires manual review")
    break
}

Checking Actor Status

Monitor an actor's budget and transaction count:

const status = await rt.actors.status(actor.id)
console.log(`Actor ${actor.name}:`)
console.log(`  Status: ${status.status}`)
console.log(`  Budget: ${status.budget.remaining} / ${status.budget.total} USDC`)
console.log(`  Transactions: ${status.txCount}`)

Error Handling

The SDK throws specific errors that you can catch and handle:

import { AuthorizationError, ExecutionError } from "@runtimee/core"

try {
  const execution = await rt.actors.pay(actor.id, { /* ... */ })
} catch (error) {
  if (error instanceof AuthorizationError) {
    console.log(`Authorization failed: ${error.message}`)
    console.log(`Error code: ${error.code}`)
  } else if (error instanceof ExecutionError) {
    console.log(`Execution failed: ${error.message}`)
  } else {
    console.log(`Unexpected error: ${error}`)
  }
}

Usage Guide

On this page