Skip to main content

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.

RoleKeys
poThe line's signers.poOps, signers.poAdmin and every key in po.apiKeys
adminThe 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:

sign-request.ts
// 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:

SignerFor
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.