Back
XCash / Docs

Technical reference for XCash — SOL payments tied to X (Twitter) identities, built on Solana.

Overview
What is XCash?
XCash lets anyone send Solana (SOL) to an X username without knowing the recipient's wallet address. Under the hood it links an X identity to a custodial Solana wallet created on first login.
How it works
  1. User authenticates via OAuth 2.0 with X (Twitter). Their X UID is stored and a Solana keypair is derived and persisted server-side.
  2. Sender calls the pay endpoint with a recipient X handle and an amount in lamports. XCash resolves the handle to a wallet address and signs the transfer.
  3. The transaction is submitted to the Solana Mainnet-Beta RPC. The tx signature is returned to the caller.
  4. Recipients can withdraw at any time to an external wallet they own.
Authentication
OAuth 2.0 via X
XCash uses X's OAuth 2.0 PKCE flow. After a successful login the server issues a short-lived session cookie (xcash_session) that is HttpOnly, Secure, and SameSite=Lax. Include it in every authenticated request.
Flow
  1. Redirect the user to GET /xauth/twitter. XCash generates a PKCE challenge and redirects to twitter.com/i/oauth2/authorize.
  2. X redirects back to /xauth/twitter/callback with a code parameter.
  3. Server exchanges the code for tokens, upserts the user record, and sets the session cookie.
  4. All subsequent API calls are authenticated via the session cookie — no Bearer token required from the client.
API Reference
GET
/api/me
Returns the authenticated user's profile: X username, display name, avatar, and linked Solana wallet address.
{
  "username": "satoshi",
  "name": "Satoshi",
  "avatar": "https://pbs.twimg.com/...",
  "wallet": "7xKX...F3Qm"
}
GET
/api/balance
Returns the SOL balance of the authenticated user's custodial wallet in lamports and SOL.
{
  "lamports": 2500000000,
  "sol": 2.5
}
POST
/api/pay
Send SOL to a recipient identified by their X handle. Requires an active session.
// Request
{
  "to": "vitalik",      // X username (without @)
  "lamports": 1000000   // amount in lamports (1 SOL = 1e9)
}

// Response
{
  "signature": "5fG3...aP9z",
  "explorer": "https://solscan.io/tx/5fG3...aP9z"
}
POST
/api/withdraw
Withdraw SOL from the custodial wallet to an external Solana address.
// Request
{
  "to": "ExternalWalletAddress...",
  "lamports": 500000000
}

// Response
{
  "signature": "3rH1...bK7w"
}
GET
/api/history
Returns a paginated list of incoming and outgoing transactions for the authenticated user.
{
  "transactions": [
    {
      "type": "received",
      "from": "elonmusk",
      "lamports": 1000000,
      "signature": "5fG3...aP9z",
      "timestamp": "2025-03-24T10:00:00Z"
    }
  ],
  "cursor": "next_page_token"
}
Error Codes
Code Status Description
UNAUTHENTICATED 401 No valid session cookie present. Redirect to /xauth/twitter.
USER_NOT_FOUND 404 The X handle does not have a registered XCash account.
INSUFFICIENT_FUNDS 400 Sender's balance is too low to cover the transfer and network fee.
INVALID_ADDRESS 400 The provided external wallet address is not a valid Solana public key.
TX_FAILED 502 The Solana RPC accepted but the transaction was not confirmed. Retry with the same parameters.
Security
Custodial key storage
User keypairs are encrypted at rest using AES-256-GCM with a server-side master key managed via environment secrets. The plaintext private key is never exposed to the client.
Rate limiting
Pay and withdraw endpoints are rate-limited to 10 requests / minute per session. Exceeding this returns a 429 Too Many Requests.
CSRF protection
Mutating endpoints (POST) validate a X-CSRF-Token header whose value is injected into the page at render time. Cookie-only requests without this header are rejected with 403.
Tech Stack
Layer Technology
Blockchain Solana Mainnet-Beta · @solana/web3.js
Auth X OAuth 2.0 PKCE
Backend Node.js · TypeScript
Session Signed HTTP-only cookies
Database PostgreSQL — user → wallet mapping
Frontend React/Vite/Tailwindcss
Terms of Service

Last updated: March 2025

1. Acceptance

By accessing or using XCash, you agree to be bound by these Terms. If you do not agree, do not use the service.

2. Eligibility

You must be at least 18 years old and legally permitted to use cryptocurrency services in your jurisdiction. By using XCash, you confirm that you meet these requirements.

3. Wallet Custody

XCash generates a Solana wallet on your behalf upon registration. Your private key is stored encrypted. XCash is non-custodial in intent — you are responsible for your wallet's security. We strongly recommend exporting and backing up your private key. XCash cannot recover lost keys.

4. Transactions

All transactions are executed on Solana Mainnet and are irreversible once confirmed on-chain. XCash is not responsible for transactions sent to incorrect addresses, failed transactions due to network conditions, or losses resulting from user error. Always verify recipient details before sending.

5. Prohibited Use

You may not use XCash for money laundering, fraud, financing illegal activity, or any purpose prohibited by applicable law. We reserve the right to suspend accounts that violate these terms.

6. Limitation of Liability

XCash is provided "as is" without warranties of any kind. We are not liable for any loss of funds, data, or profits arising from use of the service, including but not limited to network failures, smart contract bugs, or third-party service outages.

7. Modifications

We may update these Terms at any time. Continued use of XCash after changes constitutes acceptance of the revised Terms. Major changes will be announced on our X community.

8. Contact

For questions regarding these Terms, reach us on X at @xcash_app.

Privacy Policy

Last updated: March 2025

1. What We Collect

When you sign up via X OAuth, we collect your X username, display name, and profile photo. We also generate and store a Solana keypair linked to your account. We do not collect passwords, email addresses, or payment card information.

2. How We Use It

Your data is used solely to operate the XCash service — linking your X identity to your Solana wallet, executing transactions you initiate, and displaying your dashboard. We do not sell your data to third parties.

3. Blockchain Data

Transactions executed through XCash are recorded permanently on the Solana blockchain. Your public wallet address and transaction history are publicly visible on-chain. This is an inherent property of blockchain technology and cannot be changed.

4. Private Key Storage

Your private key is stored in our database. While we apply security best practices, we recommend exporting your key and managing it yourself for maximum security. We will never ask for your private key over any communication channel.

5. Third-Party Services

We use X (Twitter) OAuth for authentication and Solana RPC providers to interact with the blockchain. These services have their own privacy policies and we are not responsible for their data practices.

6. Data Retention

We retain your account data for as long as your account is active. To request deletion of your account and associated data, contact us on X. Note that on-chain transaction data cannot be deleted.

7. Contact

For privacy-related requests or questions, reach us at @xcash_app on X.

© 2025 XCash  ·  Home  ·  Commmunity  ·  Github  ·  Terms  ·  Privacy