Auth
The service issues no tokens or passwords. Each request that needs a role is signed by a Stellar key, and the line's registry says which role that key holds.
Roles
A request names a line, and the service looks up the role of the signing key on that line in the registry.
| Role | Keys |
|---|---|
po | The line's signers.poOps, signers.poAdmin and every key in po.apiKeys |
admin | The line's signers.untangledAdmin, Untangled's admin key |
Signed requests
The client signs each request that needs it with the signer given to
createClient, and adds four headers: PayFi-Key, PayFi-Signature,
PayFi-Time and PayFi-Nonce. The signature is ed25519 over the
SEP-53
digest, sha256("Stellar Signed Message:\n" + message), of this text:
PayFi request
Line: beta-2
Action: Renew the release of payout INV-0001
POST /v1/lines/beta-2/payins/INV-0001/release/renew
Body: 44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
Time: 2026-10-18T12:00:00Z
Nonce: 9f1c2a7b4e6d8a03
The action line is the service's own wording, from actionLabel in core. The
body line is the sha256 of the exact body bytes, or "-" for no body; the client
sends {} for a call with no fields. The time must be within 300 seconds of the
service's clock, and the service accepts each nonce once. A wallet that
supports SEP-53 shows the PO this text before it signs.
signRequest(signer, { method, path, body }) returns the headers for a call the
client does not make itself. This example calls whoami by hand:
// A signed request made by hand, to show what the client does for you:
// four headers over a SEP-53 message.
// bun run sign-request.ts
import { signRequest } from '@crediolabs/payfi-sdk/api'
import { keypairSigner } from '@crediolabs/payfi-sdk/signing'
function env(name: string): string {
const value = process.env[name]
if (!value) throw new Error(`Set ${name} in .env`)
return value
}
const url = process.env.PAYFI_URL ?? 'https://payfi-beta.untangled.finance'
const apiKey = keypairSigner(env('PAYFI_API_SECRET'))
const path = `/v1/lines/${env('PAYFI_LINE')}/whoami`
const headers = await signRequest(apiKey, { method: 'GET', path })
console.log(`PayFi-Key: ${headers['payfi-key']}`)
console.log(`PayFi-Time: ${headers['payfi-time']}`)
console.log(`PayFi-Nonce: ${headers['payfi-nonce']}`)
const res = await fetch(`${url}${path}`, { headers })
console.log(res.status, await res.json())
Read grants
A private read (payouts, receivers, decisions, events and take-overs) uses a
read grant. The client asks for one with a signed
POST /v1/lines/{line}/read-grants, sends it as
Authorization: PayFi-Grant <grant>, and reuses it until a minute before its 15
minutes run out. A grant only reads: it signs no step and changes no state.
Pass readGrants: false to createClient to sign every read instead.
line.grant() returns the grant the client holds, for a proxy that takes it in
a PayFi-Grant header. Read the lists
has an example.
Anyone who copies a grant can read the line's private lists until it expires, so keep it on the server that asked for it.
The two keys of an automated PO
An automated PO holds two keys. Its API key signs requests and reads the
private lists; the registry lists it under the line's po.apiKeys. Its
operations key, signers.poOps, signs the steps: the approvals the chain
checks. The examples read them as PAYFI_API_SECRET and PAYFI_OPS_SECRET.
Every signer has the same three methods, and the SDK wraps each in a check that its signature verifies against its address:
| Signer | For |
|---|---|
keypairSigner(secret) | A server key: an automated PO's API and operations keys, the operator's admin key |
walletSigner(kit) | A browser wallet through Stellar Wallets Kit |
primeWalletSigner(wallet, address) | Stellar Wallet from @crediolabs/agent-web-wallets |
approvalSigner({ address, approve }) | Fireblocks, Fordefi, Utila or any MPC wallet. It signs steps only |
keypairSigner holds the secret in process memory. A PO with real money signs
steps with approvalSigner and an MPC wallet or a hardware security module, so
the operations key never sits on its server.
When no signature is needed
A step's own signature proves a money move, so the calls that make and submit steps need no signed request. Anyone may call:
GET /v1/health,GET /v1/lines, and a line's view, basket, market, freeze state and steps;- a payout's prepare, and the release, repayment, withdrawal, PO take-over cancel and liquidation steps;
- the liquidation quote, and every step's submit.
A prepare or a step records nothing. The payout exists once the key the step names has signed it, and the service checks that key against the registry. A caller that shows a key of the line, by its read grant or a signature, is served ahead of anonymous callers on the prepare, release, repayment and withdrawal routes.
A receiver screening needs the PO's or the admin's key. The market and take-over steps, the freeze and the limits need the admin's signed request.