SDK Reference

SDK Reference

The @xrplrequest/sdk package is a TypeScript-first SDK for server-side use (Node.js 18+).

Installation

npm install @xrplrequest/sdk

Initialisation

import { XRPLRequest } from '@xrplrequest/sdk';
 
const client = new XRPLRequest({
  apiKey: 'xrplr_live_...',  // required
  baseUrl: 'https://xrplre.quest', // optional — useful for testing
});

client.payloads

.create(options) → Promise<Payload>

Create a new signing payload.

const payload = await client.payloads.create({
  type: 'signAndSubmit',
  transaction: {
    TransactionType: 'Payment',
    Destination: 'rXXX...',
    Amount: '1000000',
  },
  options: {
    expiresIn: 300,                      // seconds; default 300, max 300 (Free) / 86400 (Pro)
    returnUrl: 'https://myapp.com/done', // optional redirect after signing
    customInstructions: 'Tip for Alice', // shown to user on sign page (max 200 chars)
  },
});
 
payload.uuid        // unique identifier
payload.signingUrl  // share this with the user
payload.status      // 'pending'
payload.expiresAt   // ISO timestamp
payload.createdAt   // ISO timestamp

Payload types:

typeNeeds transactionNeeds messageDescription
connectNoNoVerify wallet ownership — no transaction submitted
signYesNoSign without broadcasting
signAndSubmitYesNoSign and broadcast to the ledger
signMessageNoYesSign an arbitrary UTF-8 string

.get(uuid) → Promise<Payload>

Fetch the current state of a payload.

const payload = await client.payloads.get(uuid);
 
payload.status        // 'pending' | 'signed' | 'rejected' | 'expired'
payload.signerAddress // populated when signed
payload.txHash        // populated when signAndSubmit resolves
payload.walletAdapter // which wallet was used
payload.resolvedAt    // ISO timestamp when resolved

.poll(uuid, options?) → Promise<Payload>

Poll until the payload leaves pending state or the timeout is reached. Returns the final Payload.

const result = await client.payloads.poll(uuid, {
  timeout: 300_000,  // ms to wait before giving up; default 300,000 (5 min)
  interval: 2_000,   // ms between checks; default 2,000
                     // Note: Free plan enforces 3s minimum server-side
  onUpdate: (payload) => {
    console.log('tick:', payload.status);
  },
});

.cancel(uuid) → Promise<Payload>

Cancel a pending payload. It transitions to expired.

await client.payloads.cancel(payload.uuid);

.list(options?) → Promise<{ payloads: Payload[] }>

List payloads for your project, newest first.

const { payloads } = await client.payloads.list({ limit: 20, offset: 0 });

client.webhooks

.create(options) → Promise<Webhook & { secret: string }>

Register a webhook URL.

const webhook = await client.webhooks.create({
  url: 'https://yourapp.com/webhook',
  events: ['payload.signed', 'payload.rejected', 'payload.expired'],
});
 
webhook.id     // save for future deletion
webhook.secret // ⚠ shown once — save this to verify incoming requests

.list() → Promise<{ webhooks: Webhook[] }>

.delete(id) → Promise<{ id: string; deleted: boolean }>

verifyWebhookSignature(secret, rawBody, signature)

Verify an incoming webhook request. Use the raw body string before JSON.parse.

import { verifyWebhookSignature } from '@xrplrequest/sdk';
 
const isValid = verifyWebhookSignature(
  process.env.WEBHOOK_SECRET!,    // the secret from webhook.create()
  rawBodyString,                   // req.body as string, NOT parsed JSON
  req.headers['x-xrpl-request-signature'] as string,
);

Also available as WebhooksClient.verify(secret, rawBody, signature).

Types

type PayloadType   = 'connect' | 'sign' | 'signAndSubmit' | 'signMessage';
type PayloadStatus = 'pending' | 'signed' | 'rejected' | 'expired';
 
interface Payload {
  uuid: string;
  type: PayloadType;
  status: PayloadStatus;
  signingUrl: string;
  expiresAt: string;       // ISO
  createdAt: string;       // ISO
  resolvedAt?: string;     // ISO, set when resolved
  signerAddress?: string;  // set when signed
  txHash?: string;         // set for signAndSubmit
  walletAdapter?: string;  // which wallet was used
}
 
interface CreatePayloadOptions {
  type: PayloadType;
  transaction?: Record<string, unknown>;
  message?: string;
  options?: {
    expiresIn?: number;
    returnUrl?: string;
    customInstructions?: string;
  };
}

Error handling

All methods throw XRPLRequestError on API errors.

import { XRPLRequestError } from '@xrplrequest/sdk';
 
try {
  const payload = await client.payloads.get('invalid-uuid');
} catch (err) {
  if (err instanceof XRPLRequestError) {
    console.log(err.message);    // human-readable error
    console.log(err.statusCode); // HTTP status code
  }
}
⚠️

poll() returns the payload in its final state even if that state is expired. It only throws XRPLRequestError if the API itself returns an error (e.g., 404 or 401).

QuickstartOverview