Introduction

This is an early, working draft of the OpenFi API reference. Endpoints, parameters, and response shapes are subject to change before the public testnet launch.

What is OpenFi

OpenFi is the infrastructure layer that lets applications, and autonomous AI agents, move money and verify identity across both traditional banking rails and blockchain rails through one API.

The four pillars

1. Bi-Directional Direct Debits

Standardized pull transactions across Web2 and Web3, live in V1.

2. Symmetrical Data Oracles

ZK-TLS financial data oracle, V2 roadmap, not yet in the API.

3. Identity & Anti-Bot Verification

W3C Verifiable Credentials for Sybil resistance, live in V1 (endpoints still placeholder).

4. Atomic Clearing & Escrows

Real-time settlement is atomic by default today; Programmatic Escrow is V2 roadmap.

See Use Cases for how these combine in practice.

Two kinds of money movement

One-time payments

A single push or pull payment. No standing authorization is created.

Agentic recurring debits

A mandate + session-key flow that lets a human or an AI agent pull funds repeatedly within strict, on-chain enforced limits.

How the API is organized

The API is split at the route level to match how these two flows actually work under the hood:

Flow	Route	Purpose
One-time payment	`POST /v1/payments`	Single push/pull, no standing authorization
Recurring agentic debit	`POST /v1/mandates`	Establishes the top-level authorization (amount, cadence, purpose)
Recurring agentic debit	`POST /v1/session-keys`	Issues a time-bound, velocity-bound cryptographic allowance scoped to a mandate
Recurring agentic debit	`POST /v1/debit-pulls`	Executes a single pull against an active session key

This same split is reflected in the SDKs as two modules: payments and agentic.

import OpenFi from "@openfi/sdk";

const client = new OpenFi({ apiKey: process.env.OPENFI_API_KEY });

// One-time payment
await client.payments.create({ amount: 2500, currency: "USD" });

// Agentic recurring debit
const mandate = await client.agentic.mandates.create({ /* ... */ });
const sessionKey = await client.agentic.sessionKeys.create({ mandateId: mandate.id });
await client.agentic.debitPulls.create({ sessionKeyId: sessionKey.id, amount: 50 });

from openfi import OpenFi

client = OpenFi(api_key="OPENFI_API_KEY")

# One-time payment
client.payments.create(amount=2500, currency="USD")

# Agentic recurring debit
mandate = client.agentic.mandates.create(...)
session_key = client.agentic.session_keys.create(mandate_id=mandate.id)
client.agentic.debit_pulls.create(session_key_id=session_key.id, amount=50)

Settlement Chains

Every OpenFi call, regardless of which route it hits, ultimately touches one of two settlement chains:

Aptos (Move): settlement router + allowance state machine (the on-chain enforcement behind mandates and session keys)
Stellar (Soroban): settlement router + attestation verifier (data-oracle / proof-of-financial-health use cases)

You don’t need to specify a chain when calling the API. OpenFi routes internally based on the request type and your account configuration.

Quickstart

Get a testnet key and make your first call.

Authentication

How API keys and signing work.

Get Started

Core Concepts

What is OpenFi

The four pillars

1. Bi-Directional Direct Debits

2. Symmetrical Data Oracles

3. Identity & Anti-Bot Verification

4. Atomic Clearing & Escrows

Two kinds of money movement

One-time payments

Agentic recurring debits

How the API is organized

Settlement Chains

Quickstart

Authentication

​What is OpenFi

​The four pillars

1. Bi-Directional Direct Debits

2. Symmetrical Data Oracles

3. Identity & Anti-Bot Verification

4. Atomic Clearing & Escrows

​Two kinds of money movement

One-time payments

Agentic recurring debits

​How the API is organized

​Settlement Chains

Quickstart

Authentication

What is OpenFi

The four pillars

Two kinds of money movement

How the API is organized

Settlement Chains