Reva

Reva

Passwordless authentication and wallet management for Reva users.

Reva provides a simple way to authenticate users, claim unique PayID names, and manage cryptocurrency balances. All authentication is passwordless using email-based OTP verification.

Authentication

Reva uses a passwordless authentication flow. Users receive a one-time password (OTP) via email, verify it, and receive an access token for subsequent operations.

Login/Register Flow

There is no difference between registration and login - both use the same passwordless flow:

1. User provides their email address
2. System sends OTP to the email
3. User provides the OTP code
4. System verifies OTP and returns access token
5. Access token is stored securely for future operations

The access token MUST be stored securely after verification and reused for all protected operations.

Available Commands

1. Login or Register

Triggers: When user wants to login, register, sign in, sign up, authenticate, or access Reva

Process:

1. Ask user for their email address if not provided
2. Call the authentication script to send OTP: {baseDir}/scripts/send-otp.sh <email>
3. Inform user that OTP has been sent to their email
4. Ask user to provide the OTP code they received
5. Call the verification script: {baseDir}/scripts/verify-otp.sh <email> <otp>
6. If successful, inform user they are now authenticated
7. The access token is automatically stored for future use

2. Claim PayID

Triggers: When user wants to claim a PayID, get a PayID name, register a PayID, or set their PayID

Requirements: User must be authenticated first (have valid access token)

Process:

1. Check if user is authenticated by calling: {baseDir}/scripts/check-auth.sh
2. If not authenticated, prompt user to login first
3. Ask user for their desired PayID name if not provided
4. Call the claim script: {baseDir}/scripts/claim-payid.sh <desired_payid>
5. Handle response:
   • Success: Inform user their PayID was claimed successfully
   • Already taken: Inform user the PayID is taken and ask for another choice
   • Invalid format: Explain format requirements and ask again
   • Unauthorized: Token expired, ask user to login again

3. View Balance

Triggers: When user wants to check balance, see wallet balance, view funds, or check how much money they have

Requirements: User must be authenticated first (have valid access token)

Process:

1. Check if user is authenticated by calling: {baseDir}/scripts/check-auth.sh
2. If not authenticated, prompt user to login first
3. Call the balance script: {baseDir}/scripts/get-balance.sh
4. Display the balance to user in a friendly format showing each token with its amount, symbol, and chain (network)
5. If unauthorized error, token expired - ask user to login again

Display Format Example:

Your current balance:
- 0.001016 ETH on Base
- 1.97 USDC on Base
- 1.21 USDT on BNB Smart Chain
- 0.80 USDC on BNB Smart Chain
- 0.00088 BNB on BNB Smart Chain

4. Get User Information

Triggers: When user asks about their account details, PayID, wallet address, email, referral code, cashback points, connected Twitter, avatar, or wants to deposit funds

Requirements: User must be authenticated first (have valid access token)

Process:

1. Check if user is authenticated by calling: {baseDir}/scripts/check-auth.sh
2. If not authenticated, prompt user to login first
3. Call the user info script: {baseDir}/scripts/get-user-info.sh
4. Extract and display the relevant information the user asked for:
   • PayID: Show from payId field
   • Wallet Address: Show from walletAddress field
   • Email: Show from email field
   • Referral Code: Show from referralCode field
   • Cashback Points: Show from cashbackPoints field
   • Connected Twitter: Show from twitter field
   • Avatar: Show from avatarUrl field
   • Transaction Limit: Show transactionLimit and transactionUsed
5. If user wants to deposit funds, provide their wallet address and instruct them to send funds to it

Important for Deposits: When user asks to deposit, simply provide their wallet address from the /api/users/me response and tell them to send funds to that address.

5. Send Funds

Triggers: When user wants to send money, send funds, send crypto, transfer tokens, or pay someone

Requirements: User must be authenticated first (have valid access token)

Process:

CRITICAL: You must parse the user's message and extract all required information to construct a proper transfer payload. Continue asking follow-up questions until ALL required fields are provided.

1. Check if user is authenticated by calling: {baseDir}/scripts/check-auth.sh
2. If not authenticated, prompt user to login first
3. Extract the following information from user's message:
   • Token Symbol: USDT, USDC, ETH, BNB, POL, or USD_STABLECOIN (these are the ONLY supported tokens)
   • Chain Symbol: ETH, POL, OP, BNB, or BASE (null for USD_STABLECOIN)
   • Recipient: PayID name, Twitter username (starts with @), or wallet address
   • Amount: Numeric value
4. If ANY field is missing, ask the user a follow-up question to get the missing information
5. Once ALL fields are collected, call: {baseDir}/scripts/send-funds.sh <tokenSymbol> <chainSymbol> <recipient> <amount>
6. Display the success message or error to the user

Recipient Type Detection:

• Twitter Username: If recipient starts with @, remove the @ and use as recipientTwitterUsername
  • Example: @aminedd4 → recipientTwitterUsername: "aminedd4"
• Wallet Address: If recipient starts with 0x, use as recipientWalletAddress
  • Example: 0x1234... → recipientWalletAddress: "0x1234..."
• PayID Name: Otherwise, use as recipientPayid
  • Example: aldo → recipientPayid: "aldo"

USD/Dollar Handling (IMPORTANT):

When user mentions 'USD', 'dollar', 'dollars', or '$':

• Set tokenSymbol to USD_STABLECOIN (this is a special marker)
• Set chainSymbol to null - the system automatically selects the network with the highest USD stablecoin balance
• DO NOT ask for network when USD/dollar is mentioned - the system handles this automatically

Supported Tokens (EXACT ENUMS):

• USDT - Tether
• USDC - USD Coin
• ETH - Ethereum
• BNB - Binance Coin
• POL - Polygon
• USD_STABLECOIN - For USD/dollar requests (chainSymbol must be null)

Supported Chains (EXACT ENUMS):

• ETH - Ethereum
• POL - Polygon
• OP - Optimism
• BNB - BNB Chain
• BASE - Base
• null - Only when tokenSymbol is USD_STABLECOIN

Parsing Examples:

Example 1: "send 5 usdt on base to aldo"

tokenSymbol: USDT
chainSymbol: BASE
recipientPayid: aldo
recipientTwitterUsername: null
recipientWalletAddress: null
amount: 5

Example 2: "transfer 0.3 BNB on bnb to @aminedd4"

tokenSymbol: BNB
chainSymbol: BNB
recipientPayid: null
recipientTwitterUsername: aminedd4
recipientWalletAddress: null
amount: 0.3

Example 3: "send $10 to chris"

tokenSymbol: USD_STABLECOIN
chainSymbol: null
recipientPayid: chris
recipientTwitterUsername: null
recipientWalletAddress: null
amount: 10

Example 4: "send 1 eth on ethereum to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

tokenSymbol: ETH
chainSymbol: ETH
recipientPayid: null
recipientTwitterUsername: null
recipientWalletAddress: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
amount: 1

Follow-up Question Examples:

• User: "send some usdt to aldo" → Missing: amount, chain → Ask: "How much USDT would you like to send, and on which network? (ETH, POL, OP, BNB, or BASE)"

• User: "send 5 usdt to aldo" → Missing: chain → Ask: "Which network would you like to use? (ETH, POL, OP, BNB, or BASE)"

• User: "send 5 usdt on base" → Missing: recipient → Ask: "Who would you like to send it to? (PayID name, Twitter handle, or wallet address)"

• User: "send $20 to aldo" → Nothing missing (USD doesn't need chain) → Execute transfer immediately

Important Notes:

• Only supported tokens are: USDT, USDC, ETH, BNB, POL, USD_STABLECOIN
• Token symbols and chain symbols must match the EXACT enums (case-sensitive)
• USD_STABLECOIN is ONLY used for USD/dollar requests
• Continue asking questions until all required fields are provided
• Do NOT make assumptions - always ask the user for missing information

Error Handling

Token Expiration

If any protected operation returns an unauthorized error, the access token has expired. Inform the user and ask them to login again.

Rate Limiting

If OTP request fails due to rate limiting, inform user to wait before trying again.

Network Errors

If scripts fail due to network issues, inform user and suggest trying again.

Invalid Input

Validate email format before sending requests. PayID format should be alphanumeric with optional underscores/hyphens.

Security Notes

• Access tokens are stored in encrypted storage at ~/.openclaw/payid/auth.json
• Never log or display access tokens to the user
• OTP codes should only be entered once and never stored
• Always use HTTPS for API requests (enforced in scripts)

Script Reference

All scripts are located in {baseDir}/scripts/:

• send-otp.sh <email> - Send OTP to email
• verify-otp.sh <email> <otp> - Verify OTP and get access token
• claim-payid.sh <payid> - Claim a PayID name
• get-balance.sh - Get wallet balance with all tokens across chains
• get-user-info.sh - Get current logged user information
• send-funds.sh <tokenSymbol> <chainSymbol> <recipient> <amount> - Transfer funds to a recipient
• check-auth.sh - Check if user is authenticated

Common Workflows

First Time User

1. User asks to login or register
2. User provides email
3. System sends OTP
4. User provides OTP code
5. User is authenticated
6. User can now claim PayID or check balance

Claim PayID

1. User asks to claim a PayID
2. Check authentication status
3. User provides desired payid name
4. System attempts to claim
5. Success or ask for alternative if taken

Check Balance

1. User asks for balance
2. Check authentication status
3. Display current balance

Get Account Info

1. User asks about their PayID, wallet address, referral code, etc.
2. Check authentication status
3. Fetch user info from /api/users/me
4. Display the requested information

Deposit Funds

1. User asks how to deposit
2. Check authentication status
3. Get wallet address from user info
4. Provide wallet address for deposits

Send Funds (Simple)

1. User: "send 0.01 usdt on bnb to aldo"
2. Forward message to Reva AI
3. Reva AI processes and sends funds
4. Display transaction confirmation with links

Send Funds (Multi-Step)

1. User: "send some funds to aldo"
2. Forward to Reva AI
3. Reva AI: "which network?"
4. User: "bnb"
5. Forward to Reva AI (same room)
6. Reva AI: "which token?"
7. User: "0.01 usdt"
8. Forward to Reva AI (same room)
9. Transaction complete with confirmation

API Endpoints

Login (Send OTP)

• Method: POST
• Path: /api/openclaw/login
• Body: {"email": "user@example.com"}
• Response: {"success": true, "message": "OTP sent to your email"}

Verify OTP

• Method: POST
• Path: /api/openclaw/verify
• Body: {"email": "user@example.com", "otp": "123456"}
• Response: {"success": true, "token": "jwt_token", "user": {...}}

Get Balance

• Method: GET
• Path: /api/wallet?isForceUpdateWallet=true
• Header: openclaw-token: <token>
• Response: {"success": true, "tokens": [{"name": "...", "symbol": "...", "balance": ..., "chain": "..."}]}

Claim PayID

• Method: POST
• Path: /api/payid/register
• Header: openclaw-token: <token>
• Body: {"payIdName": "payid_name"}
• Response: {"success": true, "data": {...}}

Get User Info

• Method: GET
• Path: /api/users/me
• Header: openclaw-token: <token>
• Response: {"user": {"id": "...", "email": "...", "payId": "...", "walletAddress": "...", "referralCode": "...", "cashbackPoints": ..., "twitter": "...", ...}}

Transfer Funds

• Method: POST
• Path: /api/message/transfer-funds
• Header: openclaw-token: <token>
• Body:

{
  "tokenSymbol": "USDT" | "USDC" | "ETH" | "BNB" | "POL" | "USD_STABLECOIN",
  "chainSymbol": "ETH" | "POL" | "OP" | "BNB" | "BASE" | null,
  "recipientPayid": string | null,
  "recipientTwitterUsername": string | null,
  "recipientWalletAddress": string | null,
  "amount": number
}

• Success Response (200): {"success": true, "data": {"message": "...", "recipientPayId": "...", "usdAmountToSend": ...}, "meta": {"message": "Transaction completed successfully"}}
• Error Response (400/500): {"success": false, "error": {"code": "...", "message": "...", "details": [...]}}

Tips

• Always check authentication before performing protected operations
• Display all token balances with their respective chains for clarity
• For deposits, simply provide the user's wallet address from /api/users/me
• CRITICAL for sending funds: Parse user's message to extract token, chain, recipient, and amount - ask follow-up questions for missing information
• USD/dollar requests use USD_STABLECOIN token with null chain - do NOT ask for network
• Only supported tokens are: USDT, USDC, ETH, BNB, POL, USD_STABLECOIN (case-sensitive)
• When user asks about account details (PayID, wallet, referral code, etc.), fetch from /api/users/me
• Provide clear error messages based on API responses
• Guide users through the authentication flow step-by-step
• Suggest alternative PayIDs if the desired one is taken
• Display transaction success messages from API responses