@reveelid/sdk

Add PayID resolution and cross-chain P2P payments to any wallet. Route-aware, type-safe, zero dependencies.

Install

npm install @reveelid/sdk

Quick Start

import { createReveel, TOKENS, NETWORKS } from "@reveelid/sdk";

const reveel = createReveel({ apiKey: "YOUR_API_KEY" });

// Resolve @username → wallet address
const { address } = await reveel.resolve("@aldo");

// Or: full flow with route matching + ready-to-sign tx
const result = await reveel.initTransaction({
  userId: "sender-uuid",
  recipientPayId: "@aldo",
  amount: 50,
  token: TOKENS.USDC,
  network: NETWORKS.BASE,
});

// result.tx → { to, data, value, chainId } — sign and submit with your wallet

What This Does

User types "@aldo" in your send field
        ↓
Your app calls: reveel.initTransaction({ recipientPayId: "@aldo", ... })
        ↓
Backend resolves PayID → matches recipient's routes → builds swap if needed
        ↓
Returns: { tx: { to, data, value, chainId }, fees: { ... } }
        ↓
Your wallet signs and submits the transaction

Reveel is the phone book + smart router. Your wallet is the phone.

Full API

resolve(payId) — The main one

const { address, payId, userId } = await reveel.resolve("@aldo");

Resolves a PayID to a wallet address. Throws ReveelError with code PAYID_NOT_FOUND if not found.

searchPayId(query, searchType?)

// Search by PayID name (default)
const results = await reveel.searchPayId("ald");

// Search by Twitter handle
const results = await reveel.searchPayId("aldothedev", "twitter");

// Search across all identifiers
const results = await reveel.searchPayId("aldo", "ALL");

Returns an array of PayIdResult:

{
  payId: string;
  userId: string;
  walletAddress: string | null;
  email: string;
  twitterUsername: string | null;
}

createUser(params) — Register users

const user = await reveel.createUser({
  email: "[email protected]",
  walletAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD15",
  twitterUsername: "aldo", // optional
});

claimPayId(userId, payId, years?) — Claim a PayID

const claim = await reveel.claimPayId(user.id, "aldo");
// Free if 13+ characters
// Returns { payId, price, expiresAt }

checkPrice(payId) — Check PayID pricing

const { price, score } = await reveel.checkPrice("eth");
// Premium short names cost more

initTransaction(params) — Initialize a transaction with route matching

Returns an unsigned transaction object for your wallet to sign and submit. If the recipient has routes configured, the backend automatically matches the route and builds a cross-chain swap transaction if needed.

const result = await reveel.initTransaction({
  userId: "sender-uuid",
  amount: 50,
  token: "USDC",
  network: "ETH",
  recipientPayId: "aldo",
});

// result.tx → { to, data, value, chainId } — ready to sign
// result.approveTx → ERC-20 approval tx (if needed)
// result.fees → { applicationFee, protocolFee, bridgeFee }

// If approval is needed, sign it first
if (result.approveTx) {
  await yourWallet.sendTransaction(result.approveTx);
}

// Then sign and submit the main transaction
const txHash = await yourWallet.sendTransaction(result.tx);

createRoute(params) — Create a receiving route

Routes define how incoming payments are handled — which networks/tokens are accepted, where funds are delivered, and whether a cross-chain swap should happen.

const route = await reveel.createRoute({
  userId: "user-uuid",
  name: "USDC on Base",
  incomingNetworks: ["ETH", "OP", "BASE"],
  incomingTokens: ["USDC", "USDT"],
  outgoingWallet: "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD15",
  // Optional: swap to a different chain/token on delivery
  swapNetwork: "BASE",
  swapToken: "USDC",
});

getRoutes(userId) — List routes

const { routes, count } = await reveel.getRoutes("user-uuid");

updateRoute(routeId, params) — Update a route

const route = await reveel.updateRoute("route-uuid", {
  userId: "user-uuid",
  incomingNetworks: ["ETH", "BASE"],
});

deleteRoute(routeId, userId) — Delete a route

await reveel.deleteRoute("route-uuid", "user-uuid");

checkRouteConflicts(params) — Check for conflicts

const { exists, conflictingRoutes } = await reveel.checkRouteConflicts({
  userId: "user-uuid",
  incomingNetworks: ["ETH"],
  incomingTokens: ["USDC"],
});

reportTransaction(params) — Report a completed tx

await reveel.reportTransaction({
  input: "send 50 USDC to @aldo",
  hash: "0xabc123...",
  confirmed: true,
  userId: "user-uuid",
  usdAmount: 50,
});

getActivities(userId, options?) — Transaction history

const { activities, pagination } = await reveel.getActivities("user-uuid", {
  page: 1,
  pageSize: 20,
});

Integration Patterns

Pattern 1: Resolve-Only (Minimum Viable Integration)

Your wallet just needs to resolve PayIDs. No user registration, no transaction tracking.

import { createReveel } from "@reveelid/sdk";

const reveel = createReveel({ apiKey: "YOUR_API_KEY" });

// In your send flow:
async function handleSend(recipient: string, amount: string) {
  let address: string;

  if (recipient.startsWith("@") || !recipient.startsWith("0x")) {
    const result = await reveel.resolve(recipient);
    address = result.address;
  } else {
    address = recipient;
  }

  // Use your wallet's normal send flow
  await yourWallet.send({ to: address, amount });
}

Pattern 2: Full Integration (Users + PayIDs + Tracking)

Register your wallet's users, give them PayIDs, and track transactions.

import { createReveel } from "@reveelid/sdk";

const reveel = createReveel({ apiKey: "YOUR_API_KEY" });

// On user signup:
async function onUserSignup(email: string, walletAddress: string) {
  const user = await reveel.createUser({ email, walletAddress });
  const claim = await reveel.claimPayId(user.id, generatePayId(email));
  return { user, payId: claim.payId };
}

// On send:
async function onSend(userId: string, recipient: string, amount: number) {
  const result = await reveel.initTransaction({
    userId,
    recipientPayId: recipient,
    amount,
    token: "USDC",
    network: "ETH",
  });

  // Sign approval if needed
  if (result.approveTx) {
    await yourWallet.sendTransaction(result.approveTx);
  }

  // Sign and submit — route matching + swap is already baked in
  const txHash = await yourWallet.sendTransaction(result.tx);

  // Report back for analytics + cashback
  await reveel.reportTransaction({
    input: result.tx.data,
    hash: txHash,
    confirmed: true,
    userId,
    usdAmount: amount,
  });
}

Pattern 3: Route-Aware Send (Smart Routing)

Let the recipient's routes determine the optimal send path.

import { createReveel } from "@reveelid/sdk";

const reveel = createReveel({ apiKey: "YOUR_API_KEY" });

async function smartSend(userId: string, recipientPayId: string, amount: number) {
  // Resolve the recipient
  const { userId: recipientUserId } = await reveel.resolve(recipientPayId);

  // Check their routes to see what they accept
  const { routes } = await reveel.getRoutes(recipientUserId);

  // Find the best match based on what the sender has
  const senderNetwork = await yourWallet.getCurrentNetwork(); // e.g. "BASE"
  const matchingRoute = routes.find((r) => r.incomingNetworks.includes(senderNetwork));

  // Init transaction — backend handles route matching + swap automatically
  const result = await reveel.initTransaction({
    userId,
    recipientPayId,
    amount,
    token: matchingRoute?.incomingTokens[0] || "USDC",
    network: senderNetwork,
  });

  if (result.approveTx) await yourWallet.sendTransaction(result.approveTx);
  const txHash = await yourWallet.sendTransaction(result.tx);

  await reveel.reportTransaction({
    input: result.tx.data,
    hash: txHash,
    confirmed: true,
    userId,
    usdAmount: amount,
  });
}

Pattern 4: Autocomplete Search

// As user types in the recipient field:
async function onRecipientInput(query: string) {
  if (query.length < 3) return [];

  const results = await reveel.searchPayId(query, "ALL");
  return results.map((r) => ({
    label: `@${r.payId}`,
    subtitle: r.twitterUsername ? `@${r.twitterUsername}` : r.email,
    address: r.walletAddress,
  }));
}

Configuration

const reveel = createReveel({
  apiKey: "YOUR_API_KEY",      // Required — your partner API key
  baseUrl: "http://...",       // Optional — custom API endpoint
  timeout: 30_000,             // Optional — request timeout in ms (default: 30s)
  retries: 2,                  // Optional — retry on network/server errors (default: 2)
});

Constants

Use the exported constants instead of hardcoding strings:

import { NETWORKS, TOKENS } from "@reveelid/sdk";

NETWORKS.ETHEREUM  // "ETH"
NETWORKS.BASE      // "BASE"
NETWORKS.POLYGON   // "POL"
NETWORKS.OPTIMISM  // "OP"
NETWORKS.BNB_CHAIN // "BNB"

TOKENS.USDC        // "USDC"
TOKENS.USDT        // "USDT"
TOKENS.ETH         // "ETH"
TOKENS.BNB         // "BNB"
TOKENS.POL         // "POL"

Error Handling

import { ReveelError } from "@reveelid/sdk";

try {
  const result = await reveel.resolve("@nonexistent");
} catch (err) {
  if (err instanceof ReveelError) {
    switch (err.code) {
      case "PAYID_NOT_FOUND":
        showMessage("This PayID doesn't exist yet");
        break;
      case "NO_WALLET_ADDRESS":
        showMessage("This user hasn't linked a wallet");
        break;
      default:
        showMessage(`Error: ${err.message}`);
    }
  }
}

Supported Chains

| Network | Constant | Code | |---------|----------|------| | Ethereum | NETWORKS.ETHEREUM | ETH | | Base | NETWORKS.BASE | BASE | | Polygon | NETWORKS.POLYGON | POL | | Optimism | NETWORKS.OPTIMISM | OP | | BNB Chain | NETWORKS.BNB_CHAIN | BNB |

Supported Tokens

| Token | Constant | Code | |-------|----------|------| | USDT | TOKENS.USDT | USDT | | USDC | TOKENS.USDC | USDC | | ETH | TOKENS.ETH | ETH | | BNB | TOKENS.BNB | BNB | | POL | TOKENS.POL | POL |

Getting an API Key

Contact [email protected] to get your partner API key.

License

MIT

reveel-sdk