For buyers.

import { Wallet } from "steelyard/buyer";

const wallet = await Wallet.create({
  project: true,
  password: "your-vault-password",
  card: { number: "4242424242424242", exp: "12/30", name: "Buyer" },
  billing: {
    email: "buyer@example.com",
    address: {
      line1: "1 Market St",
      city: "San Francisco",
      postal_code: "94105",
      country: "US",
    },
  },
  limits: { daily: { USD: 100 } },
  allowedMerchants: ["coffee.example"],
});

// Reopen later — vault is on disk, unlocked via OS keychain or password.
// await wallet.close();
// const reopened = await Wallet.open({
//   project: true,
//   password: "your-vault-password",
// });

# ~/.steelyard/policy.yaml
version: 2026-06-27
trusted_domains:
  coffee:
    - coffee.example
rules:
  - name: coffee-under-25
    do: allow
    rail: virtual_card
    when:
      merchant_domain_in: coffee
      amount_usd: { max: 25 }
      type: one_time
    limits:
      per_day_usd: 100
      per_day_count: 8

  - name: ask-user-above-25
    do: require_approval
    rail: virtual_card
    when:
      merchant_domain_in: coffee
      amount_usd: { min: 25, max: 100 }
    approval:
      who: user
      channel: webhook
      expires_in: 5m

  - name: deny-all
    do: deny

import { PolicyEngine, EcbFxQuoteService } from "steelyard/policy";
import { virtualCardRail, WebhookEventBus } from "steelyard/policy-rail-card";

const webhookBus = new WebhookEventBus();
const engine = new PolicyEngine({
  dataDir: ".steelyard/policy",
  policyPath: ".steelyard/policy.yaml",
  socketPath: ".steelyard/policy/policy.sock",
  fx: new EcbFxQuoteService(),
  clock: { now: () => new Date() },
  rails: [
    virtualCardRail({
      stripe,
      cardholderId: process.env.STRIPE_ISSUING_CARDHOLDER!,
      env: "production",
      webhookBus,
    }),
  ],
});

await engine.start();
// Agent receives caller_token + policy.sock path, not Stripe credentials.

import { Wallet } from "steelyard/buyer";
import { Steelyard } from "steelyard/buyer/client";
import type { PurchaseIntent } from "steelyard/core";

const wallet = await Wallet.open({ project: true });
const merchant = await Steelyard.connect(
  "https://coffee.example/.well-known/ucp",
);
if ("error" in merchant) throw new Error(merchant.error);
if (!merchant.supports("checkout")) throw new Error("no checkout advertised");

const intent: PurchaseIntent = {
  merchant: { domain: "coffee.example", transport_url: merchant.url, protocol: merchant.protocol },
  offer: { id: "cappuccino", title: "Cappuccino", categories: ["coffee"] },
  amount: 500,
  currency: "USD",
  intent_id: "order-001",
};

const receipt = await wallet.purchase(intent, {
  merchant,
  idempotencyKey: "order-001",
});

console.log(receipt.order_id, receipt.status, receipt.charged_amount);

import { Wallet, x402Fetch, x402Payments } from "steelyard";

const wallet = await Wallet.open({ project: true });

await wallet.addInstrument(x402Payments({
  signer,
  networks: ["eip155:84532"],
  assets: ["USDC"],
  schemes: ["exact"],
}));

const fetchPaid = x402Fetch(wallet, {
  maxAmount: { amount: "0.10", currency: "USDC" },
});

const response = await fetchPaid("https://api.example.com/paid-weather");
console.log(response.x402?.receipt.transaction);

import { Steelyard } from "steelyard/buyer/client";

const merchant = await Steelyard.connect(
  "https://coffee.example/.well-known/ucp",
);
if ("error" in merchant) throw new Error(merchant.error);

// search returns matching offers, or { error } on protocol failure.
const matches = await merchant.search("espresso");
if (!("error" in matches)) {
  for (const offer of matches) {
    console.log(offer.id, offer.title, offer.pricing[0]);
  }
}

// getOffer fetches a single offer (with description, attributes, etc.).
const cappuccino = await merchant.getOffer("cappuccino");
if (!("error" in cappuccino)) {
  console.log(cappuccino.description, cappuccino.availability);
}

import { Wallet } from "steelyard/buyer";
import { Steelyard } from "steelyard/buyer/client";
import type { PurchaseIntent } from "steelyard/core";

const wallet = await Wallet.open({ project: true });
const merchant = await Steelyard.connect(
  "https://coffee.example/.well-known/ucp",
);
if ("error" in merchant) throw new Error(merchant.error);

const idempotencyKey = "order-2026-06-27-001";

async function pay(intent: PurchaseIntent) {
  for (let attempt = 1; attempt <= 3; attempt++) {
    try {
      return await wallet.purchase(intent, { merchant, idempotencyKey });
    } catch (err) {
      if (attempt === 3) throw err;
      await new Promise((r) => setTimeout(r, 250 * attempt));
    }
  }
}

import { Wallet } from "steelyard/buyer";
import { Steelyard } from "steelyard/buyer/client";

const wallet = await Wallet.open({ project: true });

// Create (or reuse) a UCP signing key. The private key never leaves the vault.
const { kid } = await wallet.createUcpSigningKey({ algorithm: "ES256" });
const publicKey = await wallet.exportUcpSigningPublicKey();

// The merchant fetches this public key from your buyer profile (which you
// also serve over /.well-known/ucp, alongside the kid).
const merchant = await Steelyard.connect(
  "https://coffee.example/.well-known/ucp",
  {
    ucpAuth: {
      preferred: "hms",
      signing: {
        kid,
        algorithm: "ES256",
        profileUrl: "https://buyer.example/.well-known/ucp",
      },
    },
  },
);

import { Wallet } from "steelyard/buyer";
import { createUcpBuyerProfileHandler } from "steelyard/buyer/client";

const wallet = await Wallet.open({ project: true });

// AP2 uses the same vault-backed UCP signing key as HMS.
if (!(await wallet.hasUcpSigningKey())) {
  await wallet.createUcpSigningKey({ algorithm: "ES256" });
}
const ucpPublicKey = await wallet.exportUcpSigningPublicKey();

// Mount this on your buyer-side /.well-known/ucp so merchants can discover
// your AP2 capability and verify the mandate.
const profile = createUcpBuyerProfileHandler({
  signingKeys: [ucpPublicKey],
  ap2: { enabled: true },
});

import { Wallet } from "steelyard/buyer";

const wallet = await Wallet.open({ project: true });

const receipt = await wallet.purchase(intent, { merchant, idempotencyKey });
console.log(
  receipt.order_id,
  receipt.status,           // "completed" | "failed" | ...
  receipt.charged_amount,
  receipt.charged_currency,
  receipt.reference,        // { acp?: {...}, ucp?: {...} } per protocol
);

// Local ledger queries — useful for monthly reconciliation.
const lastMonth = await wallet.listReceipts({
  since: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
});
const spend = await wallet.listSpend({
  since: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
});

import { Wallet } from "steelyard/buyer";
import type { PaymentMandateIssuer, PaymentMandateRequest, PaymentMandate } from "steelyard/core";

const myRailIssuer: PaymentMandateIssuer = {
  instrumentType: "my-rail-token",

  async issueMandate(mandate: PaymentMandateRequest): Promise<PaymentMandate> {
    // Call your rail, scope the token to this mandate, return the mandate.
    const token = await myRail.createScopedToken({
      amount: mandate.payment.amount,
      currency: mandate.payment.currency,
      checkout_id: mandate.payment.checkout_id,
      merchant_id: mandate.merchant_id,
      ttl_seconds: 120,
    });
    return {
      id: token.id,
      max_amount: mandate.payment.amount,
      currency: mandate.payment.currency,
      expires_at: token.expires_at,
      scope_proof: { type: "my_rail_scope", token: token.id },
    };
  },
};

const wallet = await Wallet.open({ project: true });
await wallet.addInstrument({
  mode: "agent-native",
  type: "my-rail-token",
  label: "My rail",
  issuer: myRailIssuer,
});