SDKs and integration recipes

The workspace SDK wraps the same HTTP contract used by the resolver and registry. Use it for typed TypeScript calls; Python integrations can use the stable HTTP API directly.

Install

npm install @universal-payment/sdk

TypeScript resolver

import { ProtocolApiError, ResolverClient } from "@universal-payment/sdk";

const resolver = new ResolverClient({
  baseUrl: process.env.REZVA_API_BASE_URL!,
  apiKey: process.env.REZVA_FREE_API_KEY!,
});

try {
  const result = await resolver.resolve({
    type: "custom",
    value: "rezva-test-merchant",
  });
  const destination = result.payment_options.find((option) => option.payment_ready);
  if (result.status !== "active" || !destination) {
    throw new Error("No payable destination");
  }
} catch (error) {
  if (error instanceof ProtocolApiError && error.status === 429) {
    // Retry after the server's Retry-After interval.
  }
  throw error;
}

TypeScript registry client

import { RegistryClient } from "@universal-payment/sdk";

const registry = new RegistryClient({
  baseUrl: process.env.REZVA_API_BASE_URL!,
  apiKey: process.env.REZVA_PROVIDER_API_KEY!,
  controllerWallet: process.env.CONTROLLER_WALLET!,
  controllerAuthorization: process.env.CONTROLLER_AUTHORIZATION!,
});

const availability = await registry.getIdentifierAvailability(
  "email",
  "pay@example.com",
);
if (availability.available) {
  await registry.registerIdentifier({
    type: "email",
    value: "pay@example.com",
    payment_options: [{
      chain: "base",
      asset: "USDC",
      address: "0xRecipient…",
      network_identifier: "eip155:8453",
    }],
  });
}

Python / HTTP resolver

import os, requests

response = requests.post(
    f"{os.environ['REZVA_API_BASE_URL']}/v1/resolve",
    headers={
        "content-type": "application/json",
        "authorization": f"Bearer {os.environ['REZVA_FREE_API_KEY']}",
    },
    json={"type": "custom", "value": "rezva-test-merchant"},
    timeout=10,
)
response.raise_for_status()
resolved = response.json()

Python validation

if resolved["status"] != "active" or not resolved["payment_ready"]:
    raise RuntimeError("Destination is not payment-ready")

option = next(
    item for item in resolved["payment_options"]
    if item["payment_ready"] and item["network_identifier"] == "eip155:84532"
)

Complete wallet flow

1. Scan the QR and extract its resolver URL, type, and value.
2. Resolve the identifier and require an active, payment-ready response.
3. Display the selected chain, asset, token contract, and destination.
4. Execute the transaction in the wallet after user confirmation.
5. Wait for chain confirmation and show the transaction hash.