@ovra/sdk

Official TypeScript SDK for Ovra — the European agentic payment infrastructure.

Ovra gives any AI agent its own virtual card, spending policies, and autonomous payment capability. EU-native, GDPR-first.

Install

npm install @ovra/sdk

Quick start

import { Ovra } from "@ovra/sdk";

const ovra = new Ovra({ apiKey: process.env.OVRA_API_KEY! });

// 1. Start a workflow run — every call under this run gets correlated
const run = await ovra.runs.create({ name: "weekly-procurement" });

// 2. Create an agent with typed permissions and spending limits
const agent = await ovra.agents.create({
  name: "procurement-bot",
  permissions: ["cards.issue", "transfers.create", "wallets.read"],
  limits: { perTransaction: 50_000, daily: 200_000 },
});

// 3. Issue a virtual card bound to this agent
const card = await ovra.cards.issue({
  agentId: agent.id,
  purpose: "AWS cloud costs monthly",
});

// 4. Later — query the full workflow timeline
const timeline = await ovra.runs.get(run.id);
console.log(timeline.events);     // Every event this run produced
console.log(timeline.transfers);  // Every transfer stamped with run_id

Features

• Agents — declare autonomous actors with limits + permissions
• Cards — virtual cards, tokenized by default. Agents never see raw card data.
• Accounts — dedicated IBAN per account, EUR-native
• Transfers — account-to-account and SEPA payouts
• Split Recipes — atomic multi-leg money routing (commission splits, revenue shares)
• Workflows — correlate every call made during one agent job
• Delegations — scoped spending grants for B2B2B flows
• Typed errors — branch on error.code === "E_WALLET_INSUFFICIENT" etc.

Idempotency

Every POST is safe to retry. The SDK automatically generates an Idempotency-Key (UUIDv4) per call — same request twice returns the same response, different body with same key returns 409.

Runs (the AI-native correlation primitive)

Pass a run id to group every call made during an agent workflow:

const run = await ovra.runs.create({ name: "invoice-automation" });

// Pin every subsequent call to this run
const runScoped = ovra.withRun(run.id);
await runScoped.transfers.create({ ... });
await runScoped.intents.create({ ... });

// Later: see the complete timeline
const detail = await ovra.runs.get(run.id);

Split Recipes

Atomically debit one wallet and fan out to N legs — all commit or all roll back:

await ovra.transfers.split({
  sourceWalletId: "wal_...",
  purpose: "Commission distribution for deal #123",
  legs: [
    { destinationType: "wallet",      destinationWalletId: "wal_cobroker_...", percentage: 40 },
    { destinationType: "beneficiary", destinationBeneficiaryId: "bnf_sub_...", percentage: 15 },
    { destinationType: "wallet",      destinationWalletId: "wal_vat_...",      percentage: 19 },
  ],
});

Error handling

import { Ovra, OvraError } from "@ovra/sdk";

try {
  await ovra.transfers.create({ ... });
} catch (err) {
  if (err instanceof OvraError) {
    if (err.code === "E_WALLET_INSUFFICIENT") {
      // meta carries { available, required }
      console.log("Top up:", err.meta);
    }
    if (err.code === "E_POLICY_DENIED") {
      // agent tried to exceed a policy limit
    }
  }
}

License

MIT