OnliYou
Sign in

ONLI / CONCEPT TO IMPLEMENTATION

A complete wallet on/off ramp for an Onli platform.

One integration equips the platform with Incoming, Master and Outgoing wallets, automatically gives every member their own wallet, and lets members take that wallet beyond the ecosystem.

You are a wallet provider building an Adapter for Onli. Openfort is the worked example. The goal is the complete wallet lifecycle: platform setup, member provisioning, money in, money out and wallet portability.

Three parts of one integration

  1. Platform wallets: provision backend wallets for Incoming, Master and Outgoing. These belong to the platform treasury; an approved administrator operates them through Appliance-authorized flows.
  2. Member wallets: automatically provision or retrieve each member’s embedded wallet during authenticated onboarding. The member can receive funds, send to the platform’s Incoming account and receive platform payouts.
  3. Portable ownership: provide secure export and recovery so the member can use the same wallet outside the platform. Leaving the interface does not require abandoning the wallet or transferring its funds to a replacement address.

Follow this lifecycle through the actual Openfort code → The Onli engineering concepts below explain how those responsibilities are organized and how your provider Adapter fits.

You build the Adapter Onli talks to. Openfort is the Adapter we built and the worked example. Build the complete provider Adapter, step by step →

Download the Claude Adapter-building skill → Includes Recipe inputs, Onli authentication and the complete lifecycle implementation guide. Read the skill and installation instructions on GitHub.

Follow the member’s lifecycle

Join the platform → authenticate with Onli → automatically provision or open the member wallet → receive funds → deposit to Incoming → receive a platform payout or send funds out → securely export and use the wallet elsewhere.

Provisioning is idempotent: later sign-ins open the existing wallet. Deposit and payout settlement remain Appliance-owned Journeys. Portability means continued use of the member’s wallet and address; it is more than the ability to send funds to another wallet.

Here, on/off ramp describes funds and wallet access moving into and beyond the Onli platform ecosystem. The worked example uses USDC on an EVM network; bank or card conversion requires its own provider capability.

This is different from the ground up.

Onli is not crypto. Think of Onli as an intelligent file — a digital thing.

Crypto, by contrast, is a record on a public ledger: an entry in a blockchain that states who holds what. Control of that entry comes from a private key — the access credential, not the asset itself. Onli is not a ledger record stored in a chain of blocks. Onli is a thing, not a record.

This distinction is more than a difference in concept — it is a fundamental shift in how the system works. Records and things behave very differently, so before you build a bridge between them, it’s essential to understand that Onli does not work the way records work.

Onli keeps a record of events that have occurred to a thing, called an Oracle. A blockchain ledger, by contrast, records an event; the activity of moving a record is the record. A transfer on a chain is just an entry saying the claim moved. The activity is the record — there is no separate thing it is a record of.

Onli is different from the ground up. This is why our nomenclature is different.

Onli.Ai Works Differently Too

This is also why you need to adopt these concepts when you write for Onli.Ai. You don’t let an AI generate behavior and hope it’s right. You build a Tool first — an atomic piece of code that does one bounded thing, under one explicit contract, proven before anything depends on it. You then compose proven Tools into Workflows — reusable responsibilities that select only what the current context requires — and compose Workflows into Journeys that own one caller-visible outcome. You classify from the outcome downward and build from the atomic layer upward, so a large product surface rests on a small, proven core.

The AI interprets intent and selects an implemented Journey; it does not invent execution steps. The user asks to send funds, and the AI selects journey_send_funds. The application still needs to check the intended recipient and amount, enforce permissions, and obtain approval of the exact request. Tested Tools and Workflows constrain execution, but they do not make intent recognition or authorization automatic. The intelligence is in the intent. The execution is in the proven architecture.

The concepts

Onli uses five concepts. Each has one clear job.

Start with the outcome and break it into reusable work. Build and prove the Tools first, then compose the Workflows and Journey.

What you are building

You provide wallets. You are building an Adapter for Onli: the translator between Onli’s wallet Capability contracts and your provider’s SDK or API.

Onli’s Appliance owns the requested outcomes, business rules and action authorization. Its Journeys and Workflows call provider-independent Capabilities. Your Adapter implements the provider operations behind those contracts and returns canonical results and evidence.

Onli Appliance → Journey → Workflow → Capability → your Adapter → your provider
Onli / Appliance responsibilityYour provider Adapter responsibility
Owner identity, membership and action authorityBind the verified Owner or Appliance account reference to the correct provider wallet
Deposit and payout Journeys, accounting and conditional rebalancingProvision wallets, perform the explicitly authorized provider operation and return evidence
Choose approved provider bindings through the RecipeRegister your versioned Adapter and declare supported operations, networks and custody
Own operation recovery and completion decisionsPreserve stable operation references, expose observations and report uncertainty accurately

You do not need to build a new Appliance or rewrite its Journeys. Implement and prove the provider contract. The deposit and payout examples below explain why Onli needs each operation from your Adapter.

How Onli calls your Adapter

Imagine an Owner asks: “Send 10 USDC to my selected recipient.” This is an external wallet transfer. It does not, by itself, move an Onli thing or write an Oracle event.

  1. Intent: the AI recognizes the send outcome. The application resolves the wallet, recipient, asset and amount; it asks for missing details.
  2. Recipe: approved configuration selects the wallet Adapter, network and timing rules. A binding means the exact version selected for this operation.
  3. Resources: the wallet and transfer request hold the data. Preparation produces a quote: the exact transaction and estimated fee.
  4. Approval: the Owner authenticates and authorizes the configured behavior. The interface also shows the exact recipient, amount, network and fee for confirmation.
  5. Execution: the Journey coordinates preparation, scoped wallet recovery, submission and observation. Tools check identity, intent and evidence at each boundary.
  6. Outcome: a transaction hash means pending. Matching transaction and receipt evidence establishes the declared outcome. An uncertain response is reconciled rather than blindly sent again.

The Recipe and the request are different inputs

The Recipe says how the work is arranged. The request says what the Owner wants. Secrets belong in neither. This teaching example shows their relationship, not a new SDK request format:

{
  recipe: {
    version: "wallet-provider/v1",
    adapter: "openfort/v1",
    capability: "recovered-wallet-session/v1"
  },
  request: {
    wallet: selectedWallet,
    asset: "USDC",
    recipient: selectedRecipient,
    amount: "10"
  }
}

The wallet-provider Recipe is consumed by the wallet-session Capability. The request goes through review and becomes a confirmed quote supplied to the send Journey. Network and timing settings have their own Recipes. This implementation selects configuration in code; it does not accept arbitrary provider selections from AI output.

Identity, permission and wallet access

These answer three separate questions: Who is the Owner? May this behavior run? Can this operation access the issued wallet? A login or wallet-access token is not approval of a transfer.

Know which side owns authentication

The Appliance establishes Onli identity and behavior authorization. Your Adapter consumes the verified, scoped authority defined by its Capability contract and maps it to provider access. It does not grant permission from an email, UI selection or provider login alone.

Before connecting

The Onli integration backend needs a registered Appliance with app_symbol and app_key, the correct Onli service environment, and gRPC connections with mTLS. Send app_key as authentication metadata on each request. Keep service credentials and certificate keys on the backend.

The Owner must be active, have OnliYou installed with an initialized vault in the correct environment, and belong to a user_class with the requested behavior configured in the Appliance Tray.

  1. Resolve the Owner. Use ListOwner with condition: identity.email and the email in meta.keyword when starting from an email. Use GetOwner when you already have the Owner’s wire ID.
  2. AuthenticateOwner. Supply owner, app_symbol and a clear body. The Owner receives an OnliYou notification. The stream waits up to 60 seconds. Basic authentication verifies the Owner’s Gene; reverse-MFA adds a Master-generated string; reverse-hash uses app_salt and client_gene_sample.
  3. AuthorizeBehavior. Supply owner, app_symbol, note.behavior and note.body. Use the behavior actually configured for this Appliance and Owner’s class; do not assume a behavior named “send” exists.
  4. Check the decision. ASKED means wait. Proceed only on ACCEPTED. DENIED, EXPIRED, missing decisions and errors stop the protected operation. Persist each auth_log_id and final status before execution; use AuthLog to retrieve the request and response record.
  5. Obtain scoped wallet access. The provider backend supplies temporary access for the verified wallet. The recovery Workflow initializes the session, verifies identity, performs the permitted action and closes the session. That temporary credential is the access handoff.

Bind authorization to the intended operation and show the exact transfer for confirmation. If the recipient, amount, wallet or network changes, review and approve the changed request again. The connected Synth demo uses Onli authentication through its server gateway. Protected behavior authorization belongs in the Appliance backend; temporary wallet access alone does not authorize a transfer.

Connecting a provider

A Capability is a Tool that offers a stable operation independent of the provider. It defines the inputs, permissions, results and evidence needed to call the work complete.

An Adapter translates that contract into the provider’s API and translates the response back. Only the Capability calls its Adapter; the Workflow stays independent of the provider.

Journey → Workflow → Capability → Adapter → Provider

For a send, the Journey owns the outcome, Workflows prepare and execute it, and Tools check the request and evidence. The Recipe selects approved settings. The Resources hold the wallet, request and result.

See how we assembled the Openfort wallet, with actual code →

What you need to build

Implement the provider-backed operations required by the agreed Capabilities. Use the existing send path to see their callers and evidence requirements. Shared validation Tools and Appliance orchestration remain above your Adapter; keep provider SDK calls inside it.

The Tools

These are the responsibilities a send path needs. Most already exist in this client. A new wallet provider implements the provider-backed operations through its Adapter and reuses the shared checks.

Tool responsibilityWhat it doesImplementation reference
Validate destination and amountCheck the address and turn the amount into exact asset units.tool_validate_transfer.ts
Verify wallet identityEnsure the recovered account is the issued wallet.tool_compare_wallet_identity.ts
Read balances and estimate fees (Capability)Obtain current network observations through a provider.tool_capability_chain.ts
Verify the quote and confirmationCheck freshness and explicit approval of the exact transfer.tool_validate_transfer.ts, tool_verify_transfer_confirmation.ts
Create the operationGive the intent a stable identity and preserve its bindings.tool_create_transfer_operation.ts
Recover the wallet session (Capability)Provide scoped access to the existing account and own provider teardown.tool_capability_wallet_session.ts
Submit the approved transfer (Capability operation)Send only the confirmed payload through the recovered session.Scoped session sendTransfer method
Observe the transfer (Capability)Read the original transaction and receipt.tool_capability_observe_transfer.ts
Verify transfer evidenceMatch the observations to the exact original intent.tool_verify_transfer_evidence.ts

Tool files are under src/tool/; Capability files are under src/capability/. The table names responsibilities, not a requirement to put every responsibility in a separate new file. Complete contracts and test mappings are in docs/tool-contracts.json.

The Workflows that call your operations

Review reuses preparation. Execution reuses wallet recovery. The Journey composes execution and preserves the operation across interrupted responses. The following integration example shows the two separate user actions; it is not an automatically executing script.

The Journey that owns the outcome

journey_send_funds is the conceptual outcome. This client names its implementation journey_send_transfer. Review happens first; explicit confirmation continues that intent into the Journey. A returned hash is pending. Reconciliation supplies completion evidence later.

The surrounding application supplies session, the selected wallet and recipient, an Owner/wallet-scoped operationStorageKey, and UI callbacks. currentSessionAndWalletStillMatch prevents work from continuing after the selection changes. Obtain backend authorization before allowing the Confirm handler to execute.

import { workflow_review_transfer } from '../workflow/workflow_review_transfer.ts'
import { workflow_execute_transfer } from '../workflow/workflow_execute_transfer.ts'
import { journey_send_transfer } from '../journey/journey_send_transfer.ts'
import { createTransferConfirmation } from '../contracts/transfer-confirmation.ts'

// Step 1: called by the Review action; returns a quote without submitting.
async function reviewRequest() {
  return workflow_review_transfer({
  wallet, asset: 'USDC', recipient, amount: '10',
  destination: 'custom', storage: localStorage,
  key: operationStorageKey,
  loadIncoming: async () => '', // unused for a custom destination
  isCurrent: currentSessionAndWalletStillMatch,
  })
}
// Show the returned quote. A null quote means the context changed.

// Step 2: called only by Confirm, after backend permission checks.
async function confirmReviewedTransfer(quote: NonNullable<Awaited<ReturnType<typeof reviewRequest>>>) {
  const result = await journey_send_transfer({
    session, wallet, quote,
    confirmation: createTransferConfirmation(quote),
    key: operationStorageKey, storage: localStorage,
    isCurrent: currentSessionAndWalletStillMatch,
    send: workflow_execute_transfer,
    changed: showOperation,
  })
  showOutcome(result)
}

Expected result: review returns a quote or stops with a validation error. Confirmation submits the exact reviewed transaction and returns an operation state. A pending or indeterminate operation needs continued observation; neither is permission to submit again.

The Journey locks the operation, checks for an existing unresolved intent and persists the operation before broadcast. It never automatically repeats a broadcast after a lost response. Callers display pending or indeterminate honestly and continue observation of that same operation.

A wallet for an Appliance has two parts

Each Owner gets an embedded wallet. The Appliance uses backend wallets for Incoming, Master and Outgoing. The administrator requests treasury outcomes; the Appliance authorizes and signs those movements through its backend Adapter.

The Owner’s deposit starts with their embedded wallet sending USDC to the Appliance’s approved Incoming target. The Appliance verifies that exact arrival, settles Incoming → Master and completes the deposit accounting. A successful wallet send is only the first part of that outcome. Walk through the deposit flow and code →

The administrator requests an outcome: settle a deposit or pay an approved recipient. The payout Workflow checks Outgoing, rebalances from Master when needed, executes payment and reconciles the result. Rebalancing is an internal Workflow step. The Recipe supplies the accounts and policy; Tools perform the bounded operations.

See how the two wallet paths fit together →

Implement your provider Adapter

Your main implementation is the Adapter. It translates the agreed Capability operation into your SDK or API and translates the result back. You also supply its versioned Recipe binding and contract tests. Onli’s existing Journeys, Workflows and shared Tools call your implementation wherever its contract fits.

  1. Agree the contract. Define the wallet identity, required permission, supported operations, result states and completion evidence. State any unsupported custody, export or network behavior.
  2. Write the private Adapter. Initialize your provider, recover the exact issued account, perform the approved operation and clean up. Translate errors without exposing credentials or raw provider responses.
  3. Register it through the Capability. Add the implementation to the Capability’s private Adapter selection. Workflows call the Capability; they never import your SDK.
  4. Supply a Recipe. Select the approved Adapter version and permitted network/timing settings. Preserve that binding on each operation.
  5. Prove it. Test identity mismatch, missing approval, cancellation, cleanup, lost responses and repeated operation IDs before integrating it into the Journey.

This is the existing minimal recovery contract. It illustrates what a provider session must return; send and export require their additional contracts.

type WalletSDK = {
  waitForInitialization(): Promise<unknown>
  recover(account: string, encryptionSession: string): Promise<{
    id: string
    address: string
    chainId?: number
    accountType?: string
  }>
  logout(exportCompleted: boolean): Promise<unknown>
}

Use src/adapter/adapter_openfort.ts as the implementation reference. The encryptionSession handoff here is Openfort/Shield-specific. A different provider needs an agreed access contract with the Capability and backend; do not put an unrelated credential into that field.

How your work fits

User intent and explicit confirmation
  → Journey owns the send outcome
    → Workflows prepare, execute and reconcile
      → shared Tools check intent, identity and evidence
      → Capability owns the provider-independent contract
        → your Adapter translates to your wallet provider

Recipe selects the approved provider and settings.
Resources preserve the wallet, intent, operation and evidence.

The provider backend supplies account provisioning and permitted temporary access. Service secrets stay server-side. An access handoff is not transfer approval. See docs/GATEWAY_CONTRACT.md for this client’s Species integration contract.

Completion needs matching evidence. This client verifies current transaction inclusion, including the exact USDC event where relevant; it does not promise irreversible finality. A timeout after possible broadcast remains unresolved. Keep the original identity and binding and recover it instead of sending again.

If the bridge also changes an Onli thing, agree the Onli-side operation and Oracle event contract separately. This client supplies no Oracle-writing endpoint. A blockchain receipt proves neither that the Onli-side effect occurred nor that its Oracle was updated.

Encryption is part of the contract

In transit: use authenticated, encrypted connections between the client, Onli and your provider. Validate certificates and authenticate the caller. Where the Capability requires an encrypted message envelope, preserve its format and integrity checks; encryption does not replace permission checks.

At rest: encrypt sensitive persisted data, including wallet key material, backups, credentials and protected operation data. Keep encryption keys separate from the data, restrict access and define key rotation and recovery. Never persist plaintext private keys or session secrets in browser storage or logs.

Your Adapter must meet both requirements and document who owns the keys at each boundary. Use the agreed cryptographic formats and tested libraries; do not invent a new encryption scheme.

In this implementation, the Species proxy uses authenticated AES-256-GCM message envelopes and encrypted backup files use the existing canonical format. The proxy permits loopback HTTP for local development; production connections require HTTPS. Browser continuity records contain operation metadata and are currently stored without application-level encryption. They contain no plaintext private keys or session tokens, but encrypted storage for protected metadata and provider-side encryption at rest must be established and verified for a production integration.

Deliver the complete on/off ramp

Your Adapter must cover platform treasury provisioning, automatic member wallet provisioning, incoming and outgoing movements, and member portability. A send-only integration leaves the platform and its members without the full lifecycle.

Your provider operations

Agree these contracts for both wallet types. This table defines responsibilities; it is not a claim that this repository exports a complete backend treasury API.

Provider operationInputs from the CapabilityReturn to Onli
Provision or resolve an Owner walletVerified Owner binding, approved network and stable provisioning referenceCanonical wallet identity, address, custody and network
Provision or resolve backend treasury walletsAppliance binding and the configured Incoming, Master or Outgoing roleCanonical role-to-wallet binding; private credentials stay server-side
Read and prepareExact wallet, asset, destination, amount and networkBalance observations, exact transaction preparation and fee/expiry information
Execute an Owner transferScoped Owner-wallet access and the approved exact intentStable submission reference and pending/refused/uncertain result
Execute one backend movementAuthorized source, approved destination, exact amount and stable leg referenceProvider submission and evidence, without selecting another source or destination
Observe or reconcileOriginal operation reference and exact expected intentMatching transaction/receipt observations and their finality level
Recovery and encrypted portabilityPermitted recovery/export scope and verified wallet identityContract-defined access or encrypted artifact, cleanup and explicit unsupported results

The Workflow decides whether Outgoing needs rebalancing. Your Adapter executes the specified Master → Outgoing leg when called. It does not infer a payout, select another wallet or add a funding movement on its own.

Your deliverables

Provide the Adapter, approved Recipe binding, identity/permission mapping, recovery rules, encryption and key-management evidence, and passing contract tests. Include backend requirements and evidence from real provider testing. The reusable send architecture then calls your implementation through the Capability.

npm ci
npm run check
npm run check:security
npm run check:licenses

Start with tests/wallet-sdk.test.mjs and tests/contracts/transfer-continuity.test.mjs. These prove local contracts with test doubles; live provider verification is a separate integration step.

Return to the concepts · Open the wallet demo