Documentation

XamanProtocol is a non-custodial DeFi protocol built on the XRP Ledger and Stellar networks. It enables users to:

• Hold assets in protocol-verified vault positions
• Earn variable protocol incentives based on participation
• Receive ecosystem airdrops via on-chain distribution
• Participate in governance via the YIELD token

All protocol interactions are non-custodial. Users retain signing authority over their wallets at all times. XamanProtocol does not hold funds or control user assets.

XamanProtocol Protocol Stack
─────────────────────────────
Layer 1:  XRPL (XRP Ledger) + Stellar Network
Layer 2:  Protocol vault primitives (escrow, trustlines, claimable balances)
Layer 3:  Reward calculation engine (on-chain metrics)
Layer 4:  YIELD governance module
Layer 5:  XamanProtocol web application (non-custodial interface)

XRPL Wallets

XamanProtocol supports XRPL accounts through two mechanisms:

• Xaman (formerly XUMM): Connect via QR code sign-in. The Xaman app signs transactions locally — XamanProtocol never receives your private key.
• Email + Seed Phrase: Create an account using your email and a self-generated 12-word BIP39 seed phrase. Your seed phrase is encrypted client-side with AES-256.

Stellar Wallets

Stellar wallet connections follow the SEP-0010 Web Authentication standard. The protocol constructs a challenge transaction which your wallet signs, proving ownership without transmitting private key material.

1. User clicks "Connect with Xaman"
2. Server generates a signed-in request payload (XUMM SignIn)
3. QR code is rendered in browser
4. User scans QR with Xaman app
5. Xaman presents sign-in request to user for approval
6. User approves → Xaman signs and broadcasts
7. XamanProtocol verifies the signed payload
8. Session established with public address (no private key transmitted)

XamanProtocol staking uses native XRPL primitives rather than smart contracts. This approach eliminates programmable contract risk and leverages the ledger's built-in guarantee enforcement.

XRPL Staking via Escrow

For time-locked positions, XamanProtocol creates XRPL Escrow objects that hold XRP for a defined period. The user signs the escrow creation transaction — the escrow is enforced by the ledger consensus mechanism, not by XamanProtocol servers.

Vault Positions

Open vault positions represent active participation in protocol reward programs. Vault eligibility is determined by:

• Minimum asset holding threshold
• Wallet age and activity
• Protocol participation score
• YIELD token holding multiplier (optional)

base_rate = protocol_pool_allocation / total_eligible_vault_value
user_rate = base_rate × participation_multiplier × yield_boost
estimated_daily_incentive = user_vault_value × user_rate / 365

Note: All rates are variable and subject to daily protocol recalculation.

Protocol incentives are distributed from a protocol reward pool to eligible vault participants. The reward pool is replenished through protocol fee collection and ecosystem allocations.

Claiming Rewards

Rewards accumulate in your protocol reward balance and can be claimed at any time. Claiming initiates an on-chain transaction that transfers the accumulated reward amount to your wallet.

• XRPL rewards: settled via Payment transaction on the ledger
• Stellar rewards: distributed as Claimable Balances
• Minimum claim threshold may apply (to manage ledger transaction fees)

XamanProtocol distributes ecosystem airdrops using Stellar's Claimable Balance primitive. This allows on-chain, verifiable, non-custodial distribution of tokens directly to eligible wallet addresses.

Eligibility

Eligibility for each airdrop campaign is based on a snapshot of on-chain data at a specified block height or ledger sequence. Criteria typically include:

• Active vault position at snapshot time
• Minimum staking duration (streak requirements)
• YIELD token holding threshold
• Governance participation activity

// Claiming a Stellar claimable balance via Stellar SDK
const claimOp = Operation.claimClaimableBalance({
  balanceId: "YOUR_CLAIMABLE_BALANCE_ID",
});

const tx = new TransactionBuilder(account, { fee, networkPassphrase })
  .addOperation(claimOp)
  .setTimeout(30)
  .build();

tx.sign(userKeypair); // signed locally on user's device
await server.submitTransaction(tx);

YIELD is XamanProtocol's utility and governance token. Holders participate in protocol governance by voting on proposals that affect:

• Reward pool allocation parameters
• Vault eligibility criteria
• Protocol fee structures
• Ecosystem partnership decisions
• Airdrop campaign parameters

Non-Custodial Design

XamanProtocol is architected to never hold or access user private keys. The application follows a client-server separation:

• Client side: Key derivation, transaction signing, seed phrase handling, session token storage
• Server side: Public address indexing, reward calculation, airdrop eligibility verification, API endpoints

User Device                   XamanProtocol Server           Blockchain
──────────────────────────────────────────────────────────────────────
[Seed Phrase] → [Key Derivation]
[Private Key] → [Tx Signing] ──────────────────────────→ [XRPL / Stellar]
                [Signed Tx] ←──────────────────────────── [Tx Result]
                [Public Address] → [API Auth] → [Session]
                                               [Server reads on-chain state]
                                               [Reward calculation]
                                               [Portfolio display]

Technology Stack

• Frontend: Next.js 16, React 19, TypeScript, TailwindCSS v4
• Authentication: NextAuth v5, TOTP (otplib)
• XRPL Integration: xrpl.js v4
• Stellar Integration: stellar-sdk v13
• Database: PostgreSQL with Prisma ORM

XamanProtocol exposes a REST API for authenticated users. All API requests require a valid session token obtained through the authentication flow.

https://xamanprotocol.app/api

Public Endpoints

// Returns protocol-wide statistics
{
  "activeVaults": 12400,
  "totalParticipants": 180000,
  "networksSupported": ["XRPL", "Stellar"],
  "protocolUptime": "99.97%"
}

Authenticated Endpoints

Authenticated endpoints require an Authorization header with your session token. These are primarily used by the XamanProtocol web application.

Headers:
  Authorization: Bearer <session_token>

Response:
{
  "pendingRewards": {
    "xrp": "14.823000",
    "xlm": "0.000000",
    "yield": "2.500000"
  },
  "lastClaim": "2026-01-10T14:32:00Z",
  "rewardRate": "variable",
  "rateLastUpdated": "2026-01-14T00:00:00Z"
}