Skip to main content

Quick start

Install​

You need Bun 1.3 or later. Make a project and add the SDK with its peer, the Stellar SDK:

mkdir payfi-app && cd payfi-app
bun init -y
bun add @crediolabs/payfi-sdk @stellar/stellar-sdk@^14.4.0

bun init adds @types/bun, which brings the Node types the SDK's types use, so TypeScript needs nothing more. On Node 22.12 or later, install with npm and add @types/node as a dev dependency.

Keys​

Bun reads .env when it starts. Keep the secrets there and out of the code. The .gitignore that bun init writes already lists .env.

.env
# The signing service: the beta, on Stellar testnet
PAYFI_URL=https://payfi-beta.untangled.finance
# Your line's id, as GET /v1/lines lists it
PAYFI_LINE=my-line
# The PO's API key: signs requests and reads the private lists
PAYFI_API_SECRET=S...
# The PO's operations key: signs the steps
PAYFI_OPS_SECRET=S...
# The receiver of a payout, from your own records
PAYFI_RECEIVER=G...

The admin and liquidation examples read PAYFI_ADMIN_SECRET and PAYFI_LIQUIDATOR_SECRET the same way. Each example stops with "Set NAME in .env" when a value it needs is unset. Auth explains which key does what.

First read​

The market list and each market's view are public, so the first read needs no key. Save this as markets.ts:

markets.ts
// List the markets, then read one market's view. Public routes: no keys.
// bun run markets.ts [line]
import { createClient } from '@crediolabs/payfi-sdk/api'

const url = process.env.PAYFI_URL ?? 'https://payfi-beta.untangled.finance'
const client = createClient({ baseUrl: url })

const lines = await client.lines()
for (const l of lines) {
console.log(`${l.id}: ${l.name} on Stellar ${l.network}, borrows ${l.assets.borrow.symbol}`)
}

const id = process.argv[2] ?? lines[0]?.id
if (!id) throw new Error('The service lists no market')
const view = await client.line(id).get()
const { basket } = view
console.log(`\n${view.line.name} at ledger ${view.ledger}`)
console.log(`Debt: ${view.debt} ${view.line.assets.borrow.symbol}`)
console.log(basket.cover_bps === null
? 'Cover: no debt to cover'
: `Cover: ${basket.cover_bps} bps of the debt, ${basket.required_bps} needed`)
for (const a of basket.assets) {
console.log(` ${a.asset}: ${a.balance} at ${a.price_usd} USD, ${a.price_age_s} s old`)
}
console.log(`Open advances: ${view.open_advances?.length ?? 0}`)
console.log(`Frozen: ${view.freeze.frozen ? 'yes' : 'no'}`)
bun run markets.ts beta-2

On 25 October 2026 against the beta it printed:

beta: Testnet PO on Stellar testnet, borrows TUSD
beta-2: Testnet PO 2 on Stellar testnet, borrows TUSD
sim: Simulated PO (testnet) on Stellar testnet, borrows TUSD

Testnet PO 2 at ledger 5376331
Debt: 0 TUSD
Cover: no debt to cover
XLM: 991.3 at 0.17189020687941 USD, 133 s old
USDC: 4993 at 1 USD, 128 s old
Open advances: 0
Frozen: no

client.lines() lists every market the service serves, one per line. line.get() reads a line now, from the chain and the service's records: its debt, its basket with each price and its age, the open advances, the freeze and the limits. Amounts are decimal strings of whole tokens with up to 7 decimals.

The three testnet lines are beta and beta-2, each with a test PO, and sim, where the service plays the PO with random payouts. A PO's own line gets its own id when Untangled sets it up (Onboarding a PO).

Next, fund a payout.