Core Concepts

This page defines the objects and authorities you work with when integrating an agent. It is the conceptual spine behind the quickstart and the integration guide. The single idea to keep hold of: authority is deliberately split so that no one party can move money alone, and each object below exists to make one slice of that split explicit.

Agent identity

An agent is identified by your opaque userId and agentId within an environment under your developer organization and application client. Its cryptographic identity is an agent key whose private half lives only in your key store; Tidal records the public key, the derived XRPL account, and a monotonic generation number. Rotating the key advances the generation and requires the user's master-signed ceremony to install the new key before it can spend — a rotation is never a silent swap.

Two important properties. The agent key is used for exactly one thing — signing the agent's half of a payment. It is never reused as an API request-signing key, a webhook key, or a policy key; roles are kept separate on purpose. And Tidal never generates, imports, escrows, backs up, or operates an agent private key. If a registration times out after your key store already created the key, the SDK reuses that same key on retry rather than minting another.

The errand (budget) wallet

Each agent gets its own funded XRPL account — the budget account, one per user/app/agent authorization scope. This is the errand wallet: a real, separate account, not a compartment inside the user's main wallet and not an on-ledger spending cap bolted onto it. The user funds it from their main wallet, and its balance is the hard, ledger-enforced ceiling on worst-case loss.

The account is governed by an XRPL SignerList with quorum 2, whose members are the agent's key and Tidal's co-signer key. The user's master key stays enabled and with the user — it is never used for day-to-day payments, but it is what funds the account, installs or removes the signer list, and performs the emergency sweep. Reserves and a fee buffer are computed dynamically from live network values, not hard-coded, and a payment fails closed if it would drop the account below its reserve floor plus fee buffer.

Spending limits and policy

The user's authorization carries the policy: a per-payment cap, a daily cap, a lifetime cap, the allowed assets (XRP, RLUSD), allowed destinations or merchants where applicable, and an expiry. Updating a limit increments a policy version in place; it does not require a new wallet.

Be precise about enforcement. These limits are enforced by the policy authority refusing to approve a payment that violates them, which in turn means Tidal's co-signer withholds its signature. They are auditable service-level controls, not ledger primitives. The ledger itself enforces only two things — the two-of-two quorum and the account balance. Everything finer lives in policy. This is the honest boundary, and the security model returns to it.

Cosigning and authorization

A single autonomous payment carries two distinct approvals, and it helps to keep them apart:

1. A policy approval — the policy and risk authority independently authenticates the caller, derives the canonical payment intent itself (it does not trust an agent-supplied digest), checks it against the user's authorization and limits, and signs a versioned approval binding the exact fields of the payment. This is evidence, not a ledger signature.
2. An XRPL co-signature — Tidal's co-signer verifies that approval, checks every field of the final transaction against the approved intent, confirms the transaction type is Payment and nothing else, and only then asks its HSM/KMS-held key to produce one XRPL Signer entry.

The agent produces the other Signer entry with its own key. Two signatures, over the exact same frozen transaction, settle on the ledger. The user's separate consent — the authorization itself — is established up front through their Tidal wallet and never collapses into your API key.

Settlement on the XRPL

Settlement is an ordinary direct XRP or RLUSD Payment on the XRP Ledger, frequently as the settlement step of an x402 request. The autonomous path is restricted to direct Payment and rejects everything else — path payments, partial payments, DEX/AMM interactions, and any account-management transaction — before it even looks up an approval. There is no generic transaction-signing escape hatch. RLUSD is matched by network, issuer, and currency identity together, never by ticker alone, so a look-alike token cannot be paid.

How the pieces fit

flowchart TB
    subgraph dev["Your side"]
        agent["Agent runtime"]
        backend["Backend + Agent SDK"]
        ks["KeyStore (KMS)<br/>agent private key"]
    end

    subgraph tidal["Tidal"]
        policy["Policy &amp; risk authority<br/>authorization · limits · approval"]
        cosigner["Co-signer service<br/>HSM/KMS second key"]
        walletsvc["Wallet execution<br/>directory · idempotency · finality"]
    end

    subgraph user["User"]
        client["Tidal wallet<br/>master key"]
    end

    ledger["XRP Ledger<br/>budget account · SignerList q2"]

    agent --> backend
    backend <--> ks
    backend -->|"1 propose payment"| policy
    policy -->|"2 signed approval"| walletsvc
    backend -->|"3 agent signs half"| ks
    walletsvc -->|"4 co-sign on approve"| cosigner
    cosigner -->|"5 second signature"| walletsvc
    walletsvc -->|"6 assembled 2-of-2"| ledger
    client -->|"funds · authorizes · can sweep"| ledger

    classDef d fill:#e8f4ff,stroke:#4a90d9;
    classDef t fill:#e8fff0,stroke:#3aa76d;
    classDef u fill:#fff4e6,stroke:#d98a3a;
    class agent,backend,ks d;
    class policy,cosigner,walletsvc t;
    class client u;

Your side holds the agent key and drives the flow; Tidal splits policy from execution from co-signing so that approval, tracking, and the second signature are separate responsibilities; the user owns the master key and reaches the ledger directly. The numbered edges are the payment lifecycle, which the integration guide walks step by step.

Draft — to be finalized. The policy-and-risk authority and Tidal's wallet-execution/co-signer are distinct services with separate authoritative state; the exact deployment topology and any service naming shown to developers are being finalized. The invariant that is settled is the split of authority itself — one writer for authorization/policy, one for wallet execution and co-signing, and the agent key held only by you.