Xyra Developer Docs
Complete integration guide — SDK or Vanilla JS
Jump to section:

Integrating Xyra

Xyra is a web-based signing system for XRPL & Xahau. Any website can request a connect session and then request transaction signing. There are no extensions required, and there is no app registration required. Every action requires explicit user approval in Xyra's protected approval environment.

Open origin model
Xyra does not whitelist or pre-approve applications. User trust is based on visible domain verification.

Quick Start

Xyra SDK (Recommended)
The official Xyra SDK provides a simple, type-safe API for integrating Xyra wallet. Install it with npm and start connecting in just a few lines of code.
Install:
npm install @xyrawallet/sdk
Features:Simple API • Error handling • TypeScript support • Tree-shakeable
Connect
Start a connect flow. Xyra derives the requesting origin and returns the user's address.
Sign Transactions
Request transaction signing using the active session. Xyra validates the session + origin and returns a signed result.
Sign Messages
Sign arbitrary messages for authentication, proof of ownership, or wallet adapter integration.
Verify domain
Xyra always shows the requesting domain to the user before they approve or reject.

Connect Flow

Your app opens Xyra's approval popup at wallet.xyra.now/connect. Xyra derives the requesting origin from document.referrer, prompts the user, and then sends a CONNECT_RESPONSE back via postMessage.

Connect to wallet
Opens approval popup and returns user's address, network, and public key
import sdk from '@xyrawallet/sdk';

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

console.log('Address:', address);
console.log('Network:', network);
console.log('PublicKey:', publicKey);
Reminder
Always validate event.origin and ignore messages that are not from the Xyra approval origin.

Sign Transactions

Xyra supports signing any valid XRPL/Xahau transaction type. By default, transactions are sign-only. You can optionally request sign + submit by using signAndSubmit(). Xyra will clearly display whether a transaction will be submitted or not.

Sign Only (Recommended)
Transactions are signed but not submitted. You receive a signed transaction blob that you can submit later using your own RPC endpoint.
import sdk from '@xyrawallet/sdk';

// Sign only (default behavior)
const { tx_blob, hash } = await sdk.sign({
  transaction: {
    TransactionType: 'Payment',
    Account: address,
    Destination: 'rDESTINATION...',
    Amount: '1000000',
    Fee: '12',
    Sequence: accountSequence,
    LastLedgerSequence: currentLedger + 20
  },
  network: 'xrpl-testnet'
});

console.log('Signed TX:', tx_blob);
console.log('Hash:', hash);
// You can submit later using your own RPC endpoint
Sign & Submit (Opt-in)

Warning: When using signAndSubmit(), Xyra will submit the transaction immediately after signing. Network fees will be spent and the action is irreversible. The approval UI will clearly warn users about this.

Sign & Submit (Opt-in)
Signs and immediately submits the transaction to the network
import sdk from '@xyrawallet/sdk';

// Sign and submit (requires explicit opt-in)
const { tx_blob, hash, submitted, submitResult } = await sdk.signAndSubmit({
  transaction: {
    TransactionType: 'Payment',
    Account: address,
    Destination: 'rDESTINATION...',
    Amount: '1000000',
    Fee: '12',
    Sequence: accountSequence,
    LastLedgerSequence: currentLedger + 20
  },
  network: 'xrpl-testnet'
});

console.log('Signed TX:', tx_blob);
console.log('Hash:', hash);
console.log('Submitted:', submitted); // true

if (submitted && submitResult) {
  console.log('Result:', submitResult.engine_result);
  console.log('Message:', submitResult.engine_result_message);
}
Important Notes
Always validate event.origin. The approval UI will always show the requesting domain to the user before they approve or reject. Sign-only is the default and recommended approach for most applications.

Sign Messages

Sign arbitrary messages for authentication, proof of ownership, or wallet adapter integration. Message signing is network-agnostic and does not require any blockchain interaction or fees.

Sign an arbitrary message
Useful for authentication, wallet adapters, and proof of ownership
import sdk from '@xyrawallet/sdk';

// Sign an arbitrary message (network-agnostic)
const { address, signature, publicKey, message } = await sdk.signMessage({
  message: 'Sign in to MyApp - Timestamp: 2025-01-15T10:30:00Z',
  onProgress: (step) => console.log(step)
});

console.log('Signed by:', address);
console.log('Signature:', signature);
console.log('Public Key:', publicKey);
console.log('Message:', message);

// Verify the signature server-side using the public key
// The signature can be used for authentication or proof of ownership
Common Use Cases
  • Prove wallet ownership without sending transactions
  • Wallet adapter authentication (sign-in with XRPL)
  • Off-chain message verification
  • Authentication tokens for web applications
  • Cryptographic proof for third-party services
Security Warning
Only approve message signing requests from sites you trust. A malicious site could trick you into signing a message that looks harmless but has consequences. Always review the exact message content before signing. The approval UI will show the requesting domain and full message content.
Server-Side Verification
After receiving a signed message, verify the signature server-side using the public key. Example using ripple-keypairs:
import { verify, deriveAddress } from 'ripple-keypairs';

// Verify signature
const isValid = verify(message, signature, publicKey);

// Verify address matches public key
const derivedAddress = deriveAddress(publicKey);
const addressMatches = derivedAddress === address;

if (isValid && addressMatches) {
  // Signature is valid - user owns this address
  // Issue auth token, grant access, etc.
}

Security Model

Xyra uses an open-origin model. Any website can open the wallet popup. Trust is established by clear, user-visible domain verification inside the wallet UI. Xyra separates signing from broadcasting—transactions are never submitted unless both the application and the user explicitly approve submission.

How origins are derived
The wallet displays the requesting site based on document.referrer and validates incoming messages using postMessage event.origin. Query parameters are ignored for origin verification.
Guidance
Users should verify the domain shown in the wallet before approving any request. This is the primary trust signal in the open origin model. If you do not recognize the origin or are not expecting the request, ALWAYS REJECT IT.
Sign vs Submit
Xyra defaults to sign-only behavior. Transactions are never submitted unless both the developer explicitly sets submit: true in the request AND the user approves the submission in the approval UI. Xyra clearly displays whether a transaction will be submitted, with prominent warnings for sign+submit requests. This separation ensures users have full control over when transactions are broadcast.
Why Xyra can't silently sign
Signing happens in the approval UI and always requires explicit user approval. Apps receive only the signed output, never the seed. Xyra will not accept messages from unexpected origins.

Networks & Safety

Xyra supports both XRPL and Xahau across Testnet and Mainnet. Network context is always shown to the user in the wallet UI before approval.

XRPLXahauTestnetMainnet
XRPL vs Xahau
XRPL and Xahau are separate networks. Make sure you check which network an action is being requested for. We currently support Mainnet and Testnet on both XRP Ledger and Xahau.
Testnet vs Mainnet
Testnet uses test funds. Mainnet uses real funds and transactions are irreversible. The wallet highlights Mainnet signing with additional caution text. Mainnet is enabled by default in Xyra, allowing users to interact with production networks immediately.