Home Getting Started Quickstart

Quickstart

Last updated on May 16, 2026

Quickstart

10 minutes to your first synced transaction. This walks you through registering as a platform on OrangeRails, getting an API key, opening the Connect widget, and pulling your first transaction.

What you need before you start

If you only want to try it as a consumer (not embed in your own app), skip steps 1–3 and just sign in at orangerails.com/app.

1. Get your platform API key

In the Orange Rails dashboard, go to Settings → API tokens and click Generate token. Copy the value once; you cannot see it again.

The token is a X-Platform-API-Key header you'll send on every call.

2. Decide how your users will connect

OrangeRails uses a tiny "subaccount" abstraction so one of your customers maps to one OR subaccount. Either:

  • Let OR create them on the fly when the user opens the Connect widget (recommended for SaaS apps).
  • Pre-create them by calling POST /functions/v1/or-provision with the user's identifier in your system.

Either way, every API call from your app passes a subaccount_id so OR knows which of your users it's acting on.

3. Drop the Connect widget into your app

The widget is a popup served from connect.orangerails.com. Open it with a postMessage handshake:

const popup = window.open(
  "https://connect.orangerails.com/connect?platform=your-platform-slug",
  "or-connect",
  "width=480,height=720"
);

window.addEventListener("message", (e) => {
  if (e.origin !== "https://connect.orangerails.com") return;
  if (e.data.type === "OR_READY") {
    popup.postMessage(
      {
        type: "OR_INIT",
        platform_api_key: "your-key-here",
        subaccount_id: "your-customer-uuid",
      },
      "https://connect.orangerails.com"
    );
  }
  if (e.data.type === "OR_CONNECTION_CREATED") {
    // user finished connecting; e.data.connection_id is yours
  }
});

The user picks a source (Blink, Kraken, xpub, whatever), enters their credentials, and the widget encrypts those credentials client-side before they ever hit OR. The server stores ciphertext only — we cannot read them.

4. Pull your first transactions

Once a connection exists, call sync:

curl -X POST https://api.orangerails.com/functions/v1/or-sync \
  -H "X-Platform-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"subaccount_id":"your-customer-uuid"}'

OR fetches from the upstream source, normalizes everything into a single shape, and stores the transactions encrypted-at-rest. You read them via:

curl https://api.orangerails.com/functions/v1/or-transactions-list \
  -H "X-Platform-API-Key: your-key" \
  -d '{"subaccount_id":"your-customer-uuid"}'

You get back a JSON array of normalized transactions: id, direction, type, amount_sats or amount, currency, timestamp, counterparty, status, etc.

5. What to read next

Need help?