Documentation

Quickstart

From an empty project to a settled, auditable payment - in four short steps.

This guide gives an agent a wallet with hard on-chain spending rules, then has it pay a service per call. Every value below is an illustrative placeholder - never real account data.

Install the SDK

Add the Railo SDK to any TypeScript or JavaScript project. It bundles everything you need to create agents, set policy, and settle payments - no custody or contract code required.

npm install @railo/sdk

Initialize the client

Create a client pointed at a network. Use devnet while you build and solana for production. The rl_test_… key here is a format illustration only.

client.ts

import { Railo } from "@railo/sdk";

// Test network keys are safe to commit only as illustrative placeholders.
const railo = new Railo({
  network: "solana",        // "solana" | "devnet"
  apiKey: "rl_test_xxxxxxxx",
});

Keys are environment-scoped

Test keys can only touch test networks. A key is never a wallet - it authenticates SDK calls; spending authority lives in the on-chain policy.

Create an agent with a policy

An agent is a wallet plus a policy. The policy is written on-chain and enforced on every payment. Define three things:

dailyLimit - a rolling 24-hour ceiling on total spend.
perCall - a hard cap on any single payment.
allow - the list of service:// addresses the agent may pay.

agent.ts

const agent = await railo.createAgent({
  // The owner sets the policy; the contract enforces it.
  policy: {
    dailyLimit: "50.00",     // USDC, rolling 24h
    perCall: "0.05",         // hard ceiling per payment
    allow: [
      "service://api.search",
      "service://api.embed",
    ],
  },
});

console.log(agent.address); // 0xAgent…  (the agent's on-chain wallet)

Make a payment

Now the agent can pay. Each call passes through the policy gate, which validates the rules on-chain before any value moves. A successful call returns a signed, settled receipt.

pay.ts

const receipt = await agent.pay({
  to: "service://api.search",
  amount: "0.02",           // a fraction of a cent, in USDC
});

// Settled instantly, signed, and traceable to the policy that allowed it.
console.log(receipt.id);        // rcpt_8fK2c…
console.log(receipt.settled);   // true

Try to overspend

Ask the agent to pay a service that isn't in allow, or an amount above perCall. The call reverts at the gate - the budget can't be broken from inside the agent.

The full example

This is the entire loop end to end - create an agent, then pay per call.

quickstart.ts

import { Railo } from "@railo/sdk";

const railo = new Railo({ network: "solana", apiKey: "rl_test_xxxxxxxx" });

// Give an agent a wallet with hard, on-chain spending rules
const agent = await railo.createAgent({
  policy: {
    dailyLimit: "50.00",                 // USDC
    perCall: "0.05",
    allow: ["service://api.search", "service://api.embed"],
  },
});

// The agent pays per call - the policy gate enforces the limits on-chain
const receipt = await agent.pay({
  to: "service://api.search",
  amount: "0.02",
});

console.log(receipt.id, receipt.settled); // instant, auditable

Next steps

Understand the moving parts in Core concepts.
Look up exact method signatures in the SDK reference.
Wire settlement events in Receipts & webhooks.
Ship safely with the Going to mainnet checklist.

Install the SDK#

Initialize the client#

Create an agent with a policy#

Make a payment#