unirail
Request early access

Unirail v1 API reference

The v1 API has 23 endpoints at api.unirail.dev, grouped here by what they do. The OpenAPI document and the docs describe each one in full, with request and response schemas.

Read the docs OpenAPI document

Basics

Base URL
https://api.unirail.dev
Auth
Authorization: Bearer ur_test_sk_…, sent from your server only. Request early access to get a key.
Version
unirail-version: 2026-10-08. The SDK sends it for you.
Writes
Every write takes an Idempotency-Key. A retry with the same key can't create a second payment.
Accounts
Given as payto:// addresses and returned masked. Decide mode takes fp_ fingerprints.

Endpoints

Decide mode

Get routing decisions from masked metadata, report outcomes and read the snapshot that a self-hosted engine uses (self-hosting is by arrangement). How Decide mode works.

  • POST /v1/outcomes Report how a decided operation went (updates reliability and contract usage)
  • POST /v1/route_decisions Decide the rail and cost for an operation from masked metadata (no names or account numbers)
  • GET /v1/routing_snapshot Get everything the decision engine reads, for running @unirail/router yourself (no secrets)

Payments

Price the routes between two accounts and create a payment from the quote your user accepted. Pay by bank.

  • POST /v1/payment_intents Create a payment intent from an accepted quote (your provider moves the money)
  • GET /v1/payment_intents List payment intents
  • GET /v1/payment_intents/{id} Retrieve a payment intent
  • POST /v1/payment_intents/{id}/advance Continue after the user returns from approving
  • POST /v1/payment_intents/{id}/cancel Cancel a payment intent
  • POST /v1/route_quotes Find and price the routes between two accounts

Accounts

Register account details a payee gave you and list the accounts your customers linked, with addresses masked.

  • POST /v1/accounts Register account details a payee gave you (not linked through a provider)
  • GET /v1/accounts List accounts
  • GET /v1/accounts/{id} Retrieve an account

Addresses

Check and mask a payto:// address before you use it, without storing it.

  • POST /v1/addresses/parse Validate and mask a payto:// address without storing it

Customers

Create one customer for each user id in your system to keep that user's links and accounts together.

  • POST /v1/customers Create or return the customer for your user id
  • GET /v1/customers List customers
  • GET /v1/customers/{id} Retrieve a customer

Institutions

List the banks your environment's connections can reach.

  • GET /v1/institutions List the banks reachable through this environment's connections

Rails

List the provider catalogue, with integrated and listed rails. Browse providers.

  • GET /v1/rails List the integrated and listed rails in the provider catalogue

Events

Read every event in order. Webhooks deliver the same events, signed.

  • GET /v1/events List events in order; page with `after` to replay anything a webhook missed
  • GET /v1/events/{id} Retrieve an event

Before your first call

QuickstartGet a test key, set up the SDK and make your first decision. Decide modeWhat a decision request carries and what stays in your backend. SecurityHashed keys, signed webhooks and credentials read from your vault.