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.
# 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:
// 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.