Xyra SDK

Official JavaScript/TypeScript SDK for integrating Xyra wallet into your dApp.

Features

• ✅ Simple API - Connect and sign in just a few lines
• ✅ TypeScript Support - Full type definitions included
• ✅ No Session Management - Simple, stateless integration
• ✅ Error Handling - Clear, actionable error messages
• ✅ Progress Callbacks - Real-time feedback for users
• ✅ Tree-shakeable - Minimal bundle size impact
• ✅ Framework Agnostic - Works with React, Vue, Angular, or vanilla JS

Installation

npm install @xyrawallet/sdk
# or
yarn add @xyrawallet/sdk
# or
pnpm add @xyrawallet/sdk

Quick Start

import sdk from '@xyrawallet/sdk';

// 1. Connect to wallet (for authentication)
const { address } = await sdk.connect({
  network: 'xrpl-testnet'
});

// 2. Sign a transaction
const { tx_blob, hash } = await sdk.sign({
  transaction: {
    TransactionType: 'Payment',
    Account: address,
    Destination: 'rN7n7otQDd6FczFgLdlqtyMVrS627LzqDA',
    Amount: '1000000'
  },
  network: 'xrpl-testnet'
});

console.log('Transaction hash:', hash);

API Reference

sdk.connect(options)

Connect to Xyra wallet to get the user's address. This is used for authentication and determining which wallet to use for transactions.

Parameters:

• options.network (required) - Network to connect to: 'xrpl-mainnet', 'xrpl-testnet', 'xahau-mainnet', 'xahau-testnet'
• options.onProgress (optional) - Callback for progress updates

Returns: Promise<ConnectResponse>

const response = await sdk.connect({
  network: 'xrpl-testnet',
  onProgress: (step) => console.log(step)
});

console.log(response.address);   // 'rABC123...'
console.log(response.network);   // 'xrpl-testnet'

Connect + Sign (Combined Flow)

If your dApp needs to verify wallet ownership at login, pass message to connect(). Both steps are handled in a single popup — no second signMessage() call needed, and no browser popup-blocking issues.

const { address, network, publicKey, signature } = await sdk.connect({
  network: 'xrpl-testnet',
  message: `Sign in to MyApp — ${Date.now()}`,
  onProgress: (step) => setStatus(step)
});

// signature and signedMessage are populated when message is provided
// Verify the signature server-side using publicKey + address

If the user rejects either step, the promise rejects with PopupClosedError.

sdk.sign(options)

Sign a transaction (without submitting to network).

Parameters:

• options.transaction (required) - XRPL/Xahau transaction object
• options.network (required) - Network name
• options.onProgress (optional) - Callback for progress updates

Returns: Promise<SignResponse>

const response = await sdk.sign({
  transaction: {
    TransactionType: 'Payment',
    Account: address,
    Destination: 'rN7n7...',
    Amount: '1000000'
  },
  network: 'xrpl-testnet'
});

console.log(response.tx_blob);   // Signed transaction blob
console.log(response.hash);      // Transaction hash
console.log(response.submitted); // false

sdk.signAndSubmit(options)

Sign a transaction and submit it to the network.

Parameters: Same as sign()

Returns: Promise<SignResponse> (with submitted: true and optional submitResult)

const response = await sdk.signAndSubmit({
  transaction: {
    TransactionType: 'Payment',
    Account: address,
    Destination: 'rN7n7...',
    Amount: '1000000'
  },
  network: 'xrpl-testnet'
});

console.log(response.submitted); // true
console.log(response.submitResult?.engine_result); // 'tesSUCCESS'

Error Handling

The SDK throws specific error types for different scenarios:

import sdk, {
  PopupBlockedError,
  PopupClosedError,
  TimeoutError,
  InvalidNetworkError
} from '@xyrawallet/sdk';

try {
  await sdk.connect({ network: 'xrpl-testnet' });
} catch (error) {
  if (error instanceof PopupBlockedError) {
    alert('Please allow popups for this site');
  } else if (error instanceof PopupClosedError) {
    console.log('User closed the popup');
  } else if (error instanceof TimeoutError) {
    console.log('Request timed out');
  } else {
    console.error('Unexpected error:', error);
  }
}

Configuration

You can create a custom SDK instance with configuration:

import { XyraSDK } from '@xyrawallet/sdk';

const sdk = new XyraSDK({
  walletUrl: 'https://wallet.xyra.now',  // Custom wallet URL
  timeout: 300000,                       // 5 minutes
  popupWidth: 420,
  popupHeight: 720,
  signPopupHeight: 640
});

Advanced Usage

Progress Feedback

Provide real-time feedback to users during connection and signing:

await sdk.connect({
  network: 'xrpl-testnet',
  onProgress: (step) => {
    // step values: 'Opening wallet...', 'Waiting for user approval...', 'Connected!'
    setStatus(step);
  }
});

Custom Transaction Types

The SDK supports all XRPL and Xahau transaction types:

// NFT Mint
const response = await sdk.sign({
  transaction: {
    TransactionType: 'NFTokenMint',
    Account: address,
    URI: '697066733A2F2F...',
    Flags: 8,
    TransferFee: 5000,
    NFTokenTaxon: 0
  },
  network: 'xrpl-mainnet'
});

// Trust Line
const response = await sdk.sign({
  transaction: {
    TransactionType: 'TrustSet',
    Account: address,
    LimitAmount: {
      currency: 'USD',
      issuer: 'rN7n7otQDd6FczFgLdlqtyMVrS627LzqDA',
      value: '1000'
    }
  },
  network: 'xrpl-mainnet'
});

TypeScript Support

The SDK is written in TypeScript and includes comprehensive type definitions:

import {
  XyraSDK,
  ConnectOptions,
  ConnectResponse,
  SignOptions,
  SignResponse,
  Network,
  XyraError,
  PopupBlockedError,
  PopupClosedError,
  TimeoutError,
  InvalidNetworkError
} from '@xyrawallet/sdk';

Examples

See the examples directory for complete working examples:

• Vanilla JavaScript - Simple HTML integration
• React - React component example
• Examples README - Detailed example documentation

Browser Compatibility

The SDK works in all modern browsers that support:

• ES2020 JavaScript
• window.open() for popups
• postMessage() for cross-window communication

Security

The SDK implements several security measures:

• Origin Validation - Only accepts messages from the configured wallet URL
• No Private Keys - Private keys never leave the wallet popup
• HTTPS Only - All wallet URLs are upgraded to HTTPS
• User Approval - Every transaction requires explicit user approval

Troubleshooting

Popup Blocked

If users have popup blockers enabled, the SDK will throw a PopupBlockedError. Handle this by instructing users to allow popups for your site.

Timeout

The default timeout is 5 minutes. If users take longer, increase the timeout in the config:

const sdk = new XyraSDK({
  timeout: 600000 // 10 minutes
});

How It Works

1. Connect: User selects which wallet address to use
2. Sign: User approves transaction signing
3. Origin Validation: Every request validates the origin for security
4. No Sessions: Simplified architecture - no session IDs to manage

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

License

MIT

Changelog

0.2.0

• feat: Added optional message parameter to connect() for a combined connect + sign flow. When provided, both steps are handled in a single popup — resolving browser popup-blocking issues for dApps that need ownership verification at login. ConnectResponse now includes optional signature and signedMessage fields populated when this flow completes successfully.

0.1.4

• feat: Added optional submit parameter to sign(). When true, the wallet submits the signed transaction to the network and returns a submitResult. Equivalent to calling signAndSubmit() but usable inline in sign().

0.1.3

• fix: Removed unreliable window.opener.origin check that was blocking connect approvals in certain browser configurations.

0.1.2

• feat: Added WebAuthn PRF biometric authentication as an alternative to password for existing wallets. Users can authenticate with Face ID, Touch ID, or Windows Hello.

0.1.1

• fix: Network parameter normalisation — xrpl-mainnet and xahau-mainnet are now accepted aliases in addition to the canonical xrpl / xahau values.

0.1.0

• Initial release with connect(), sign(), signAndSubmit(), and signMessage().

Support

For issues and questions:

• Documentation: https://xyra.now/developers