Seeker Mobile Guide

Chainrails offers a React Native SDK for integrating payments into Solana Seeker mobile apps, with built-in access to the Seeker dApp wallet, the Seeker theme, and features designed specifically for Seeker devices. This guide walks you through the complete end-to-end setup to get Chainrails payments working in your Solana Seeker mobile app.

Overview

This guide uses @chainrails/react-native on the app side for the payment modal and hooks, and @chainrails/sdk on your backend to create session tokens. For the broader React Native integration, see Mobile Development.

Prerequisites

Before you begin, make sure you have:

A React Native project
A Chainrails API key from dashboard.chainrails.io
A backend service where you can create session tokens securely

Step 1: Install the SDK

Install the React Native UI package in your app and the core SDK on your backend.

App
Backend

npm install @chainrails/react-native

npm install @chainrails/sdk

Step 2: Set Up Session Endpoint

Create a backend endpoint that generates secure session tokens. The mobile app calls this endpoint right before opening the payment modal.

// server.js (Node.js / Express example)
const express = require("express");
const { Chainrails, crapi } = require("@chainrails/sdk");

const app = express();
app.use(express.json());

Chainrails.config({
  api_key: process.env.CHAINRAILS_API_KEY,
});

app.post("/create-session", async (req, res) => {
  try {
    const { amount, recipient, destinationChain, token } = req.body;

    const session = await crapi.auth.getSessionToken({
      amount: amount ?? "10",
      recipient,
      destinationChain,
      token,
    });

    res.json(session);
  } catch (error) {
    res.status(500).json({
      message: "Failed to create payment session",
      error: error instanceof Error ? error.message : "Unknown error",
    });
  }
});

At minimum, validate recipient, destinationChain, token, and amount before creating a session. For a Seeker-targeted flow, the destination chain is typically SOLANA. In your app, fetch a session from your backend and open the payment modal only after the session is ready.

// App.jsx
import { useCallback, useState } from "react";
import { Button, SafeAreaView, StatusBar, StyleSheet, Text, View } from "react-native";
import { PaymentModal, usePaymentModal } from "@chainrails/react-native";

export default function App() {
  const [status, setStatus] = useState("Ready");

  const cr = usePaymentModal({
    sessionToken: null,
    onCancel: () => setStatus("Payment cancelled"),
    onSuccess: (result) =>
      setStatus(result?.transactionHash ? `Payment successful — ${result.transactionHash}` : "Payment successful"),
  });

  const pay = useCallback(async () => {
    setStatus("Creating session…");
    try {
      const res = await fetch("https://your-server.com/create-session", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          amount: "10",
          recipient: "YourSolanaWalletAddress",
          destinationChain: "SOLANA",
          token: "USDC",
        }),
      });

      if (!res.ok) throw new Error("Could not create payment session");

      const data = await res.json();
      cr.updateSession({ sessionToken: data.sessionToken, amount: data.amount });
      setStatus("Session ready — opening payment modal");
      cr.open();
    } catch (err) {
      setStatus("an error occured");
    }
  }, [cr]);

  return (
    <SafeAreaView style={styles.root}>
      <StatusBar style="light" />
      <Text style={styles.title}>Pay with Chainrails</Text>

      <View style={styles.actions}>
        <Button title="Open Chainrails payment" onPress={pay} />
      </View>

      <Text style={styles.status}>{status}</Text>

      <PaymentModal
        {...cr}
        client={{
          name: "Your App Name",
          logoUrl: "https://your-app.com/logo.png",
          paymasterEnabled: false,
        }}
      />
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  root: { flex: 1, backgroundColor: "#111", padding: 20, gap: 16 },
  title: { color: "#fff", fontSize: 22, fontWeight: "700" },
  actions: { gap: 10 },
  status: { color: "#9ad", fontSize: 12 },
});

Run it with:

npx expo run:android

Best Practices

Never expose API keys client-side: Always use a backend session endpoint
Validate all inputs: Check recipient addresses, chains, tokens, and amounts
Use HTTPS: Ensure all communications are encrypted
Implement rate limiting: Prevent session endpoint abuse

Additional Notes

Live API keys cannot be used with test networks. In test environments you can use supported mainnets and testnets, but once you switch to a live API key you must use mainnet networks only.
Testnets also do not have indexing support. If you are testing the modal on a testnet, users must click I have made payment after funding. If you are using API-driven flows, you must manually call POST /api/v1/intents/{intent_address}/trigger-processing to process the intent.

Next Steps

See the Mobile Development guide for the broader React Native integration details
See the Payment Modal reference for hook behaviour and parameters

Github Example

Check out our Github demo repository for a full React Native example.

Introduction

Concepts

Developer Guides

Essentials

Overview

Prerequisites

Step 1: Install the SDK

Step 2: Set Up Session Endpoint

Best Practices

Additional Notes

Next Steps

Github Example

​Overview

​Prerequisites

​Step 1: Install the SDK

​Step 2: Set Up Session Endpoint

​Step 3: Open the Payment Modal

​Best Practices

​Additional Notes

​Next Steps

Github Example

Overview

Prerequisites

Step 1: Install the SDK

Step 2: Set Up Session Endpoint

Step 3: Open the Payment Modal

Best Practices

Additional Notes

Next Steps