SDK Integration Guide

const ramp = createRampClient({
  environment: "staging",
  partnerId: "your-issued-partner-id",
  apiBaseUrl: "https://api.pilot.example",
  paneOrigins: ["https://pane.pilot.example"],
  sendStore,
  requestTimeoutMs: 15_000,
});

const sendStore = createZecSendStore({
  get: key => secureWalletStorage.get(key),
  set: (key, value) => secureWalletStorage.set(key, value),
});

await sessionVault.saveCreationIntent(partnerSessionId);
const session = await ramp.createSession({
  direction: "sell",
  asset: "ZEC",
  fiat: "BRL",
  returnUrl: "mywallet://ramp",
  partnerSessionId,
});
await sessionVault.save(session);

const bridge = ramp.attachPaneBridge({
  sessionRef: session.sessionRef,
  transport,
  onZecSendRequest: async (request, { signal }) =>
    wallet.confirmAndSend(request, { signal }),
  onReady: () => {},
  onResult: () => { void refreshAuthoritativeStatus(); },
  onSendRecoveryRequired: () => showRecoveryScreen(),
  onClose: () => teardownPane(),
  onProtocolError: () => { bridge.close(); },
});

interface PaneTransport {
  post(message: unknown): void;
  subscribe(handler: (raw: unknown) => void): () => void;
}

if (!ramp.isAllowedPaneUrl(session.sessionUrl)) throw new Error("origin refused");
loadWebView(session.sessionUrl);

await bridge.sendZecSendResult(requestId, verifiedTxid);

await bridge.sendZecSendCancel(requestId, reason);

const status = await ramp.getStatus(session.sessionRef);
// { outcome, terminal, zecTxids?, fiat?, updatedAt }

const session = ramp.restoreSession(await sessionVault.load());
await ramp.getStatus(session.sessionRef);

const parsed = ramp.parseReturnUrl(url);
// { sessionRef, outcome, claimsTerminal, params }

// 1 -- create the session as usual (returnUrl scheme rules above)
const session = await ramp.createSession({
  direction: "sell",
  asset: "ZEC",
  fiat: "BRL",
  returnUrl: "mywallet://ramp", // your scheme, registered and routed by your app
  partnerSessionId,
});
await sessionVault.save(session);

// 2 -- validate the pane URL, register the return-link listener FIRST, then
// open the auth-session browser (host-owned platform API, e.g. expo-web-browser;
// confirm the exact call signature against your installed version)
if (!ramp.isAllowedPaneUrl(session.sessionUrl)) throw new Error("origin refused");
const sub = Linking.addEventListener("url", ({ url }) => handleReturn(url));

// 3 -- await the open; consume its result -- expo-web-browser resolves it
// when the sheet closes, and it may carry your return link
const result = await openAuthSessionAsync(session.sessionUrl, "mywallet://ramp",
  { preferEphemeralSession: false });
if (result.type === "success" && result.url) handleReturn(result.url);
// keep the listener registered across restarts and foregrounding; remove it
// only on teardown (sub.remove())

function handleReturn(url: string) {
  // Your app owns scheme and host routing. Link claims never set the session outcome.
  try {
    const target = new URL(url);
    if (target.protocol !== "mywallet:") return;
    const parsed = ramp.parseReturnUrl(url);
    if (parsed.sessionRef === session.sessionRef) void refreshStatus();
  } catch { /* malformed or unrelated link */ }
}