# Agent Wallets on Straddle ## Executive summary Agent Wallets are a product design that gives software agents bounded authority over stored value. The agent never owns the funds and never touches raw payment rails. The business remains the Account Owner. It owns and funds the Balance and delegates only the authority an agent needs. A machine user identifies and authenticates the agent's activity. The delegation defines permitted actions, spending limits, destinations, and approval requirements. Straddle applies those rules at the money-movement boundary, reserves funds in Bedrock, and executes approved movements through its existing payment infrastructure. This design makes agent payments useful beyond a closed agent ecosystem. An agent can pay an external vendor through the vendor's paykey. The vendor needs no agent, machine user, Agent Balance, or separate agent network. The business keeps ownership and control. The agent gets enough authority to do the job. ## Reading guide The proposal has five parts and two appendixes: - Sections 1 through 6 define the product, current Straddle foundation, roles, and trust boundaries. - Sections 7 through 18 define the proposed authorization, Balance, funding, policy, security, and user experience. - Sections 19 and 20 explain agent interfaces and protocol interoperability. - Sections 21 through 26 define proposed interfaces, controls, and evidence requirements. - Sections 27 through 29 define MVP templates, delivery phases, and unresolved decisions. - Appendix A analyzes AP2 and x402 compatibility. Appendix B holds the full Delegation Mandate example. Read by role: - First read: sections 1 through 4, then 27 through 29. These cover the product, scope, terms, architecture, templates, roadmap, and open decisions. - Security review: add sections 6 through 8, 15, 16, and 19. - Compliance review: add sections 10, 11, 23, and 24. - Implementation: add sections 9, 13, 14, 21, and 22. ## 1. Product thesis Agent Wallets let verified Account Owners delegate limited payment authority to software agents. The software agent proposes a balance read, funding request, internal transfer, external payout, or request for Owner approval. The machine user authenticates that request. The Owner's mandate, current policy, and spendable `agent` Balance constrain every action. This proposal extends Pay by Bank's identity, bank connectivity, paykeys, ACH Payments, and webhooks with delegated authority and policy-controlled Balance movement. ([Straddle Docs][6], [Straddle MCP][40]) ## 2. Scope ### In scope for MVP - An `agent` category in the Account-scoped Balance product. - Machine-user provisioning and API keys. Registered-public-key evidence is an MVP dependency only if the approved evidence model requires it. - Bounded, long-running delegation records. - Human-present transaction approvals for step-up. - Movement status, Payment status, Balance Transfers, and audit artifacts. - ACH top-ups through current Charge primitives: Receiver-initiated for consumer accounts through an Owner surface, or sponsor-approved for non-consumer accounts. - Funds held until the approved spendability threshold. - Internal Balance transfers through Bedrock. - External payments through the current ACH Payout path. - Policy evaluation before every movement. - Revocation, idempotency, replay protection, and audit linkage. - AgentPay tools added to Straddle MCP as the primary agent interface. - A Movement API for approved direct integrations. ### Deferred - x402 transport and settlement support, including a Bedrock mechanism and any external-network integration. - Autonomous consumer ACH replenishment until the Receiver affirmative-action model is approved. - Request for Payment (RfP) initiation until sender access, sponsor approval, and receiving coverage support the use case. - Stablecoin settlement. - Card-funded Balance top-ups and push-to-card payouts. - Instant advances until underwriting, consumer-credit treatment, and recovery processes are approved. - Free-form natural-language policy generation. - Full merchant-category enforcement unless destination category data is available. - Customer-owned Balance. Supporting it requires a separate product and legal decision. ### Non-goals - Making the agent the customer of record. - Letting the model choose payment rails directly. - Putting a machine-user API key inside model context. - Asking an agent to construct raw HTTP requests for money movement. - Using paykeys as bearer credentials. - Treating an open-banking token as a one-time verification event. - Creating a separate deposit account, FBO structure, or ledger for each agent. ## 3. Key terms ### Customer A person or business involved in a payment transaction in Straddle's data model. A Customer is not interchangeable with an embedded Account. In the current model, a Customer can hold a paykey and act as an external payment counterparty, but Balance is Account-scoped. ### Embedded Account An onboarded business whose payment activity a platform attributes through `Straddle-Account-Id`. The Account owns the current Account-scoped Balance. Customers under it do not automatically own that stored value. ### paykey A reusable payment token linking a verified Customer to a supported bank account. The current create Payout endpoint accepts the paykey token string, not a paykey resource ID. In this proposal, a paykey is a funding or destination credential, not the legal actor record. ([Straddle Docs][7]) ### Owner The verified Account that owns the current Account-scoped Balance. Each machine user belongs to one Owner. The Owner remains the legal principal for funds, authorization, and loss-bearing treatment under the stored-value program. Customer-owned Balance is a separate open product decision. The machine user is a technical delegate and never owns the funds. The existing program and account agreements continue to govern returns, provisional credit, negative balances, fraud, and unauthorized activity. ### Bedrock Straddle's real-time double-entry ledger, built on TigerBeetle. Bedrock supports immutable two-phase transfers. The first transfer reserves funds as pending. A second immutable transfer posts or voids the reservation. A pending transfer can expire automatically without a resolution transfer. Pessimistic account invariants prevent overspending. ### Agent Balance The proposed `agent` category in the Owner's Account-scoped Balance. It allocates stored value for machine-user spending without creating another account or ledger. Section 9 defines its relationship to the live Balance schema. ### Agent A software operator, not a legal person, authorized to act through a machine user. It is never the customer of record. ### Machine user The API principal that authenticates downstream requests proposed by a software agent. It belongs to one Owner and can hold multiple API keys that share one authority and budget. A registered public key, if the approved evidence model requires one, verifies signed evidence but never replaces bearer authentication. ### Mandate A proposed Straddle-signed authorization artifact backed by verified evidence of what an Owner approved. The proposed Straddle model uses the following internal artifacts: - **Delegation Mandate:** reusable, bounded authority granted by the Owner. - **Movement Approval:** single-use Owner approval for a specific movement. - **Movement:** durable lifecycle record linked to policy, Bedrock transfers, and any Payment ID. These are Straddle-specific artifacts. They borrow AP2's principles of bounded authority and verifiable evidence, but they are not AP2 credentials. Appendix A defines the separate adapter that provides AP2 wire compatibility for qualifying checkout flows. ### Movement service The proposed authoritative service for money-movement authorization and orchestration. It authenticates the machine user, resolves the Owner, verifies mandates and required evidence, evaluates policy, reserves funds, selects one policy-eligible rail, invokes the Payment path, and records Movement status. ### Policy engine The deterministic rule evaluator that decides whether a proposed action is permitted. It consumes the mandate set, Balance state, Owner risk state, paykey state, destination state, funding policy, and request context. ### Funding posture The program-approved risk and liquidity mode for Agent Balance funding. Examples: `hold_until_eligible` at launch, with `instant_advance` and `released_funds_only` as future modes. ### Open-banking connection A live account-connectivity relationship created through Bridge or supported third-party open-banking tokens. In this design, the connection is part of paykey health and funding risk posture, not merely an onboarding artifact. Bridge already supports its own widget, manual bank-account entry, and third-party tokens such as Plaid, MX, and Finicity. ([Straddle Docs][9]) ### RfP A Request for Payment is a non-value message that asks a payer to initiate a separate instant credit transfer. It is not a debit or pull rail. Section 10.3 defines its treatment in this proposal. ### AFT An Account Funding Transaction (AFT) pulls funds from an eligible Visa account to fund an eligible non-merchant account. Card funding is outside the MVP. Section 10.2 defines its treatment. ### OCT An Original Credit Transaction (OCT) pushes funds to an eligible card account. Push-to-card payouts are outside the MVP. Section 10.2 defines their treatment. ## 4. Conceptual architecture
Agent Wallets system map showing the Owner, agent, Straddle control point, Bedrock ledger, and current and future payment rails.
The Account Owner delegates bounded authority. The software agent proposes actions through AgentPay. The machine user authenticates them. Movement authorizes and orchestrates money movement.
The proposed AgentPay handler validates typed arguments and may reject malformed or locally disallowed input, but it cannot authorize money movement. Movement makes the authoritative decision. Policy determines eligible rails. Movement selects and orchestrates one within those constraints. AgentPay and approved direct integrations reach the same enforcement point and cannot bypass it through Charge, Payout, Balance Transfer, or Bedrock writes.
Architecture diagram separating the Owner, software agent, Straddle control point, and external payment rails.
Movement is the control point behind the agent-facing interface. It verifies authority, applies policy, writes the ledger, and orchestrates the selected rail.
### External vendor payment flow The following flow is authoritative for a proposed payment to an external vendor: 1. The Account Owner allocates stored value to `agent` and approves a Delegation Mandate. 2. A software agent calls an AgentPay tool through its MCP client to propose `movement.payout.create`. The agent does not own funds. 3. The existing Straddle MCP server invokes the proposed AgentPay handler. The machine user authenticates the downstream request, and the handler applies its API key outside model context. The agent never receives the credential. 4. Movement verifies the authenticated machine user, the mandate, and any required evidence; applies policy; validates the vendor's paykey token; and selects one eligible rail. For the MVP, that rail is ACH. 5. Movement creates its lifecycle record and a Bedrock pending transfer that reserves the amount. 6. Movement creates the existing Payout with the vendor's paykey token. 7. The exact Bedrock-to-Payout handoff remains an open implementation decision. Any handoff must preserve the single-debit-path invariant in section 9. 8. A pre-submission failure voids the reservation. An unused pending transfer may expire automatically without a resolution transfer. 9. Payment and Balance Transfer status history update the Movement. A later return or reversal adds compensating ledger entries and events without rewriting immutable Bedrock transfers or the Movement's original request and authorization evidence. The vendor can be a verified Customer with a paykey but needs no Agent Balance, machine user, or software agent. ## 5. Relationship to current Straddle primitives ### Customers The Owner maps to an embedded Account. Customer creation normally initiates inline or background identity verification and risk assessment in the current Straddle model. Identity supports know-your-customer and know-your-business checks, fraud scoring, watchlist checks, and ongoing monitoring. Identity also lets Straddle verify an external payment counterparty without requiring that party to open a stored-value Balance or join an agent network. ([Straddle Docs][10]) ### Bridge and paykeys Bridge creates paykeys by linking Customer identity to account ownership. A Customer can have multiple paykeys. For Agent Wallets, a paykey becomes a funding source or external payout destination only when current status and policy permit it. ([Straddle Docs][9]) ### Charges Agent Balance funding is a Charge against the approved funding paykey belonging to the designated ACH Receiver. Existing Charge fields map as follows: | Charge field | Agent Wallet usage | | ---------------------- | ---------------------------------------------------------------------------- | | `paykey` | Approved funding paykey for the designated ACH Receiver | | `amount` | Top-up amount in the smallest currency unit | | `currency` | USD | | `payment_date` | Funding initiation date | | `consent_type` | Current Straddle enum for the approved authorization channel | | `device.ip_address` | Authorization device IP, or `0.0.0.0` for documented offline consent | | `external_id` | Movement ID | | `config.balance_check` | Policy-selected balance-check mode | | `metadata` | Owner ID, mandate ID, machine-user ID, funding posture | The mandate remains linked to the Charge as supporting evidence. It does not replace the required ACH authorization record. Preserve the original authorization context and a separate initiation record for each autonomous funding request. The Charge status lifecycle also matters. Once a Charge reaches `pending`, Straddle has sent it to the network and cannot stop it. ([Straddle Docs][2]) ### Payouts Movements from an `agent` Balance to an external bank account use the current ACH Payout primitive. The current create Payout endpoint accepts the destination paykey token string. Future RTP or FedNow routing requires a separate Movement integration. ([Straddle Docs][3]) ### Open-network payment roles Agent Wallets require delegation only on the paying Account side. An external counterparty can be a Customer with a paykey and needs no Agent Balance, machine user, or agent. The following table distinguishes the two common business flows: | Business goal | How money moves | What the external party needs | | --- | --- | --- | | Let an agent pay a vendor | The agent proposes `movement.payout.create`. Movement reserves the Owner's `agent` Balance and creates an ACH Payout with the vendor's paykey token. | Verified Customer identity and an eligible destination paykey. | | Collect from a customer | The business uses the existing Charge flow against the payer's authorized paykey. AgentPay tools can govern the agent's request to create that movement, but they do not replace ACH authorization. | Verified Customer identity, an eligible funding paykey, and valid payment authorization. | The external side continues to use Identity, paykey, Charge, and Payout controls. ### Funding events Straddle generates funding events as part of payments to support reconciliation. Agent Wallets should link funding events to Balance Transfers, Bedrock transfer IDs, Movement IDs, Payment IDs, and authorization IDs. ([Straddle Docs][21]) ### Request tracing and idempotency AgentPay tools and the Movement API should inherit Straddle's existing API patterns: - Machine-user API-key authentication on downstream Movement requests. - `Request-Id` for individual call tracing. - `Correlation-Id` for operation-level tracing. - `Idempotency-Key` for safe retries. - Standard response envelopes with `meta`, `response_type`, and `data`. Straddle documents `Request-Id` and `Correlation-Id` for tracing across operations. Straddle separately documents idempotency keys for safely retrying state-changing requests without duplicate operations. ([Straddle Docs][22], [Straddle Docs][14]) ## 6. Trust boundaries Agent Wallets have four separate trust domains.
Trust-boundary diagram for the Owner, agent, Straddle control point, and payment rail.
Authority begins with the Owner, is constrained for the agent, and is enforced by Movement before external execution.
### 6.1 Owner trust domain An authorized representative completes the approval ceremony for long-running authorizations and may approve individual transactions for the Owner. The applicable program and account agreements assign responsibility for the funding source, returns, fraud, and any provisional credit. Apply the following Owner-domain controls: - Account and authorized-representative verification. - paykey ownership verification. - Owner approval credential. - Out-of-band approval for step-up. - Mandate revocation. - Funding posture selection. ### 6.2 Machine-user trust domain The software agent proposes actions through a machine user but cannot authorize beyond the mandate. The machine user has no independent right to funds. Apply the following machine-user controls: - Machine-user API-key issuance, rotation, and revocation. - Public-key registration, verification, rotation, and revocation if the evidence model requires it. - One Owner for each machine user. - AgentPay tool authorization and downstream Movement service access only. - Shared authority across all keys, with no key inside model context. ### 6.3 Movement-service trust domain Movement decides whether to execute a request. AgentPay can reject input earlier, but cannot approve or bypass this decision. Apply the following Movement-service controls: - Mandate verification. - Machine-user authentication on requests from Straddle MCP or an approved direct integration. - Owner resolution. - Policy evaluation. - paykey health checks. - `agent` Balance and limit checks. - Policy-constrained rail selection. - Bedrock reserve, post, or void operations and automatic-expiry handling. - Movement, Payment, Balance Transfer, and webhook linkage. ### 6.4 Rail trust domain Current ACH and internal Bedrock transfers have different timing, finality, and return profiles. Push-to-card, RTP, and FedNow are future Movement routing options. Apply the following rail-domain controls: - Rail eligibility. - Destination support. - Settlement windows. - Return and reversal handling. - Provisional balance rules. - Advance limits. - Reserve management. ## 7. Mandate model Agent Wallets use two authorization artifacts and one Movement record. All schemas in this section are proposed Straddle-native formats, not AP2 schemas.
Authorization flow from Owner-approved Delegation Mandate through Movement policy evaluation, step-up approval, execution, and receipts.
A Delegation Mandate defines standing authority. Movement Approval supplies one-time step-up evidence.
### 7.1 Delegation Mandate A long-running, scope-bound authorization issued and signed by Straddle after verified Owner approval. It defines what an agent can do without real-time Owner approval. Delegation Mandates are reusable until expiry or revocation. They are not bearer credentials. They are signed policy documents. #### Proposed Delegation Mandate fields All integer money fields in the proposed JSON examples use the smallest currency unit. For USD, `25000` means $250.00. The following example shows the fields this section discusses. Appendix B holds the full example with every proposed sub-object, including velocity, purpose, and funding policy. ```json { "type": "DelegationMandate", "id": "dmd_01HZX...", "version": "2026-05-17", "subject": { "owner_type": "account", "owner_id": "d93c9b02-5b41-4f3a-91e4-43cd736dd90f", "balance_category": "agent" }, "authorized_actor": { "machine_user_id": "musr_...", "public_key_fingerprint": null }, "capabilities": [ "balance.read", "movement.payout.create", "movement.approval.request" ], "spend_policy": { "currency": "USD", "max_per_transaction": 25000, "max_per_day": 100000, "allowed_destinations": [ { "type": "paykey_token", "token": "paykey-token-value" } ], "step_up": { "required_above": 25000, "required_for_new_destination": true } }, "validity": { "issued_at": "2026-05-17T15:00:00Z", "expires_at": "2026-08-17T15:00:00Z" }, "revocation": { "status_endpoint": "/v1/mandates/dmd_01HZX/status", "revocation_version": 1 }, "owner_approval_evidence": { "type": "webauthn", "assertion_hash": "sha256:...", "approved_content_hash": "sha256:..." }, "straddle_signature": { "alg": "EdDSA", "kid": "straddle_signing_key_...", "value": "..." } } ``` #### Policy meaning A Delegation Mandate answers the following questions: - Which Owner, machine user, Balance category, actions, and destinations are in scope? - Which amount, velocity, funding, and step-up rules apply? - When does the authority begin, expire, or become revoked? `public_key_fingerprint` is optional until Straddle selects the agent-evidence model. If it is present, the mandate binds the registered public-key version used for covered evidence. ### 7.2 Movement Approval A per-transaction Owner approval. Movement requires one when: - The request exceeds the Delegation Mandate envelope. - The Delegation Mandate explicitly requires step-up. - The destination is new. - The policy engine detects elevated risk. - The funding posture would create new advance exposure. - The transaction is human-present by product design. Movement Approvals are single-use and context-bound. #### Proposed Movement Approval fields This example is separate from the sufficient-balance INV-1045 scenario in section 21. ```json { "type": "MovementApproval", "id": "map_01HZY...", "delegation_mandate_id": "dmd_01HZX...", "subject": { "owner_type": "account", "owner_id": "d93c9b02-5b41-4f3a-91e4-43cd736dd90f", "balance_category": "agent" }, "authorized_actor": { "machine_user_id": "musr_..." }, "transaction": { "operation": "movement.payout.create", "amount": 37500, "currency": "USD", "destination": { "type": "paykey_token", "token": "paykey-token-value" }, "purpose": "invoice_payment", "description": "Invoice INV-2048", "reference": "inv_2048" }, "funding": { "top_up_required": true, "top_up_amount": 25000, "funding_method": "ach_debit", "risk_posture": "hold_until_eligible" }, "execution_constraints": { "single_use": true, "nonce": "n_...", "expires_at": "2026-05-17T15:15:00Z", "max_clock_skew_seconds": 60 }, "owner_approval_context": { "channel": "hosted_approval", "ip_address": "203.0.113.7", "user_agent_hash": "sha256:...", "device_binding": "webauthn:..." }, "owner_approval_evidence": { "type": "webauthn", "assertion_hash": "sha256:...", "approved_content_hash": "sha256:..." }, "straddle_signature": { "alg": "EdDSA", "kid": "straddle_signing_key_...", "value": "..." } } ``` #### Required security properties - Single use, expiry, and nonce protection. - Explicit amount, destination, Owner, and machine-user binding. - A hash of the displayed approval content and human-presence classification. Whether Movement Approval also binds an immutable public-key ID or fingerprint, and how that binding survives key rotation, remains an open design decision. ### 7.3 Movement record A Movement is the durable lifecycle resource for one machine-user request. Its original request, authorization, and evidence fields are immutable. Status can change through a mutable current view or append-only events. The record links any mandate, approval, Bedrock transfer, and Payment. Payment and Balance Transfer resources also have mutable status and status history. A Payment can reach `paid` and later become `reversed`. Bedrock ledger transfers alone are immutable. Later returns or reversals use additional transfers and lifecycle events. The following example shows the proposed Movement fields: ```json { "id": "mov_01HZZ...", "owner": { "type": "account", "id": "d93c9b02-5b41-4f3a-91e4-43cd736dd90f", "balance_category": "agent" }, "machine_user_id": "musr_...", "agent_evidence": null, "authorization": { "delegation_mandate_id": "dmd_01HZX...", "movement_approval_id": null }, "operation": "movement.payout.create", "amount": 10000, "currency": "USD", "destination": { "type": "paykey_token", "token": "paykey-token-value" }, "status": "submitted", "bedrock": { "pending_transfer_id": "bdtxn_pending_...", "resolution_transfer_id": null }, "payment": { "type": "payout", "id": "5088f4bc-b3df-4d61-9274-5de69f70226d", "status": "pending" }, "idempotency_key": "agent-op-...", "request_id": "req_...", "correlation_id": "corr_...", "created_at": "2026-05-17T15:01:00Z", "updated_at": "2026-05-17T15:01:02Z" } ``` `resolution_transfer_id` is present when a second Bedrock transfer posts or voids the reservation. Automatic expiry requires no resolution transfer. A separate Straddle compensation record for expiry, if needed, would be a proposed audit feature rather than a Bedrock requirement. ## 8. Credential and key model ### 8.1 Owner authorization ceremony The MVP uses Web Authentication (WebAuthn) as evidence of the Owner's approval, not as a general-purpose document-signing key. Straddle canonicalizes the proposed mandate, computes its hash, and creates a random, single-use WebAuthn challenge. The challenge binds the mandate hash, operation purpose, nonce, and expiry. After the Owner approves, Straddle verifies the credential ID, challenge, origin, relying-party identifier, user-presence flag, user-verification flag, signature, and signature-counter state. Straddle stores the complete assertion and exact canonical mandate bytes. The Movement service then issues the signed Delegation Mandate and links it to the verified WebAuthn assertion. Use a distinct challenge purpose for mandate approval. Product policy may require a credential separate from account login, but WebAuthn does not require a separate credential. ([WebAuthn][27]) ### 8.2 Machine-user credentials Straddle issues API keys to a machine user. Multiple keys support rotation without creating another identity or budget. If policy requires agent-signed evidence, the approved design also registers a public key. The public key verifies evidence but never authorizes an API request by itself. Apply the following controls to each key: - Restrict authorization to downstream Movement service requests. - Deny direct calls to Charge, Payout, Balance Transfer, and Bedrock write endpoints. - Store the key in the Straddle MCP credential boundary or an approved direct-integration secret store, outside model context. - Support rotation and immediate revocation. - Attribute every request to the machine user and Owner. Apply the following controls to the registered public key: - Bind the key to the same machine user and Owner. - Verify agent-signed evidence for operations that require it. - Keep private signing material outside model context. - Preserve an explicit public-key rotation and revocation history. - Do not accept the public key or its signature as bearer authentication. ### 8.3 MCP and downstream authentication The agent calls an AgentPay tool through Straddle MCP. The proposed extension validates the tool arguments, resolves the machine user, and retrieves its API key outside model context. It then forwards the requested operation to Movement with Straddle's request tracing and idempotency headers. The following headers describe that downstream service request, not agent input: ```http Authorization: Bearer MACHINE_USER_API_KEY Content-Type: application/json Idempotency-Key: op_vendor_inv_1045 Request-Id: req_01J... Correlation-Id: corr_inv_1045 Straddle-Account-Id: d93c9b02-5b41-4f3a-91e4-43cd736dd90f ``` The API key resolves the machine user and Owner. Movement rejects an inactive key, mismatched Owner or Balance, missing authority, invalid required evidence, or unfulfilled Movement Approval. Signer custody depends on the evidence model. A Straddle-hosted signer in the MCP credential boundary proves use of that hosted key. It does not prove that a separate external runtime produced the request. An approved external runtime must provide its own verifiable evidence when policy requires that proof. Which model applies to each operation remains open. ### 8.4 Chain of custody Every movement links the following evidence: 1. Owner approval for the mandate or Movement Approval. 2. Machine-user bearer authentication. 3. Required agent evidence, if the approved model uses it. 4. The policy decision and resulting Movement, Bedrock, Balance Transfer, Payment, and webhook records. ## 9. Agent Balance model Agent Wallets add one category to the current Account-scoped Balance product. They do not add a parallel wallet ledger or stored-value liability.
Agent Balance availability formula, balance fields, ledger accounts, and accounting invariants.
The Balance view maps spendability states to ledger accounts while preserving one rail instruction per ledger movement.
### Balance categories The live Balance response has top-level `total`, `available`, `incoming`, `outgoing`, and `categories` fields. Current category values are `available`, `charges`, `payouts`, `reserve`, `revenue`, `returns`, and `pending`. `total` is not a category. The proposal adds `agent` to `categories`. Moving $2,000 from the `available` category to `agent` changes the category allocation but not top-level `total`. Whether `agent` also contributes to top-level `available`, or remains separately spendable and excluded from that field, is an open API and accounting decision. ### Bedrock reservations and concurrency Bedrock already supplies the required reservation primitive through immutable two-phase transfers: 1. Create a pending transfer to reserve the requested amount. 2. Post it when the one authoritative debit succeeds, or void it before submission. 3. Let an unused pending transfer expire automatically when its timeout passes. Pending debits count against the applicable account invariant before posting. This pessimistic check prevents concurrent requests from overspending the `agent` Balance. Bedrock evaluates reservations in request acceptance order. A request that exceeds the remaining capacity fails. A later smaller request can still pass. A voided or expired reservation restores capacity. The exact Bedrock-to-Payout handoff remains an open implementation decision. Any implementation must preserve the single-debit-path invariant: the existing Payout pipeline must not independently debit a second Balance source for the same Movement. ### Machine-user limits Limits attach to the machine user, not to individual API keys or mandates. Every key for the machine user draws from the same machine-user budget. The `agent` Balance provides the aggregate financial ceiling, while policy can apply lower transaction and velocity limits. Creating or rotating a key does not create new spending capacity. Every Movement links its Bedrock reservation and any downstream Payment. Current Balance Transfer resources expose mutable lifecycle status and status history, a `deposit` or `withdrawal` direction, and one of these categories: `available`, `charges`, `payouts`, `reserve`, `revenue`, or `returns`. Top-up and cash-out are operations, not Balance Transfer types. ## 10. Funding ### 10.1 ACH debit through paykey-backed charge This is the default launch funding method. It requires an active, approved funding paykey for the designated ACH Receiver. Process an ACH-funded top-up as follows: 1. For a consumer account, the Receiver takes affirmative action through the Owner surface. For a non-consumer account, the Owner or agent initiates only under a sponsor-approved model. 2. Movement checks the mandate, ACH authorization, paykey status, open-banking freshness, and any required balance signal. 3. Movement creates a Straddle Charge against the approved funding paykey belonging to the designated ACH Receiver. 4. Bedrock records pending inbound funding and holds it until risk policy releases the paid Charge. Release does not end return or dispute risk. 5. Charge status updates and funding events reconcile to the Agent Balance. Straddle documents balance-check modes for Charges: enabled, required, and disabled. Agent Wallets should map funding posture to those modes. High-risk or high-value top-ups should require balance confirmation. Lower-risk flows can attempt the balance check and proceed when it is unavailable. ([Straddle Docs][2]) ### 10.2 Future card-funded Balance top-up Card funding is outside the MVP and requires a separately approved Visa Direct program. An AFT can pull funds from an eligible Visa account to fund an eligible non-merchant account. An OCT can push funds to an eligible card account. The program requires a licensed acquirer or acquirer sponsorship, network and use-case approval, correct transaction classification, dispute operations, reconciliation, fraud controls, and applicable card-data controls. ([Visa Developer][20]) A successful AFT authorization confirms issuer approval at that stage. It does not establish final settlement. Bedrock should first record the amount as pending inbound funding. Making the amount spendable before the approved settlement threshold is a separate provisional-credit or advance decision with explicit exposure, reversal, chargeback, and recovery rules. ### 10.3 Future instant funding and RfP RTP and FedNow payments are credit pushes. An RfP is a non-value message that asks the Owner to initiate a separate instant credit transfer. Acceptance of an RfP does not itself move or settle funds. Network settlement treatment applies to the resulting accepted credit transfer. ([Federal Reserve Financial Services][12], [The Clearing House][16]) For future instant funding, use the following posture: - Accept inbound push credits to the Agent Balance where operationally available. - Do not make RfP a launch dependency. - Add RfP only when sender access, payer experience, network rules, sponsor approval, and receiving coverage support the use case. - Treat RfP as an initiation method, not as a rail or proof of settlement. ### 10.4 Outbound rails The MVP supports internal Bedrock transfers and ACH Payouts. Future Movement routing may add: - RTP payout, where destination supports it. - FedNow payout, where destination supports it. - Card push payout through OCT, if enabled and approved. The agent does not choose the rail. The agent specifies intent: ```json { "operation": "movement.payout.create", "amount": 10000, "currency": "USD", "destination": { "type": "paykey_token", "token": "paykey-token-value" }, "preference": "ach" } ``` Policy determines the eligible rails from the following inputs, and Movement selects and orchestrates one: - Mandate policy. - Destination eligibility. - Balance category. - Settlement certainty requirement. - Cost ceiling. - Risk posture. - Rail availability. - Cutoff windows. - Compliance state. ## 11. Funding posture One approved posture applies to each mandate. The MVP supports only `hold_until_eligible`. The other rows remain future designs subject to program, sponsor-bank, legal, and risk approval. | Posture | Status and spendability | Typical conditions | Owner disclosure | | --- | --- | --- | --- | | `hold_until_eligible` | MVP. ACH funding remains unspendable until risk policy releases the paid Charge. Release does not end return or dispute risk. | Large amounts, new Owners, stale or weak bank signal, low negative-balance tolerance, or higher-risk use cases. | The agent cannot spend ACH-funded money until Straddle releases it. A later return may still affect the Balance. | | `instant_advance` | Future. Approved pending funding becomes spendable up to an advance limit. | Strong bank signal, low return history, bounded top-ups, and time-sensitive workflows. | The agent can spend before settlement up to the approved limit. The agreement assigns returned-debit loss. | | `released_funds_only` | Future. Only risk-released funds or an approved instant source are spendable. | High-risk categories, strict compliance contexts, or no tolerance for advance exposure. | The agent can spend only risk-released funds or funds received through an approved instant source. | ## 12. Open banking as a live funding signal Open banking is a live risk signal, not a one-time setup step. For Agent Wallets, each funding paykey should expose a health object: ```json { "paykey_id": "e9f5de32-9d68-4e95-aaab-0f2c257db8ec", "status": "active", "health": "verified_and_healthy", "source": "plaid", "open_banking": { "connected": true, "last_successful_refresh_at": "2026-05-17T14:55:00Z", "balance_available": true, "balance_last_checked_at": "2026-05-17T14:59:00Z", "ownership_signal": "matched", "account_status": "open", "risk_flags": [] } } ``` The proposal suggests the following health states: | State | Meaning | Funding behavior | | -------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------- | | `verified_and_healthy` | Identity, ownership, account status, and recent signal are good. | Full policy eligibility. | | `verified_but_stale` | Historical verification exists but live signal is stale. | Require refresh, lower caps, or `hold_until_eligible`. | | `verified_but_constrained` | Account is valid but balance, velocity, or risk flags constrain funding. | Lower caps, require Movement Approval, or switch rails. | | `review_required` | paykey or customer state requires review. | No autonomous funding. | | `ineligible` | Closed, blocked, rejected, or unauthorized source. | Deny funding. | The health object extends current paykey status with Agent Balance funding semantics. Straddle's current paykey statuses include `pending`, `active`, `inactive`, `rejected`, `review`, and `blocked`. Agent Wallets should add an Agent Balance-specific health interpretation instead of overloading the public status field. ([Straddle Docs][7]) ## 13. Policy engine The policy engine should be deterministic, inspectable, and non-generative. No LLM should author final executable policy. The LLM may suggest a policy template, but the Owner approves only a compiled, canonical policy through the ceremony in section 8.1. ### Policy dimensions | Dimension | Examples | | ----------- | ----------------------------------------------------------- | | Actor | machine-user ID and Owner ID | | Action | read balance, fund, transfer, payout, request approval | | Amount | per-transaction, daily, weekly, monthly caps | | Velocity | count per time window, amount per time window | | Destination | Account Balance allowlist, paykey allowlist | | Purpose | invoice, API access, contractor payout, reimbursement | | Time | business hours, expiration, embargo windows | | Funding | permitted rails, max advance, required freshness | | Risk | paykey health, Customer risk score, destination risk | | Step-up | thresholds, new destination, fast rail, stale signal | | Compliance | sanctions status, watchlist status, blocked jurisdiction | | Rail | allowed outbound rails, settlement profile, cost ceiling | ### Policy outcome ```json { "decision": "approved", "reason": "within_delegation_mandate", "matched_mandate_id": "dmd_...", "requires_movement_approval": false, "funding_required": true, "funding_plan": { "method": "ach_debit", "amount": 25000, "risk_posture": "hold_until_eligible" }, "rail_plan": { "movement_type": "payout", "preferred_rail": "ach", "fallback_rail": null } } ``` ### Deny reasons Use stable machine-readable reason codes: | Code | Meaning | | ---------------------------- | ---------------------------------------------- | | `machine_user_unauthorized` | Machine user cannot use AgentPay Movement operations. | | `api_key_revoked` | Machine-user API key is no longer active. | | `mandate_not_found` | No active mandate covers the request. | | `mandate_expired` | Mandate has expired. | | `mandate_revoked` | Mandate has been revoked. | | `policy_amount_exceeded` | Amount exceeds policy cap. | | `policy_velocity_exceeded` | Velocity limit exceeded. | | `destination_not_allowed` | Destination is not permitted. | | `movement_approval_required` | Step-up approval is required. | | `paykey_not_active` | Funding or destination paykey is not active. | | `paykey_stale` | Funding paykey signal is stale. | | `balance_insufficient` | Agent Balance lacks spendable funds. | | `funding_not_allowed` | Funding policy does not permit top-up. | | `advance_limit_exceeded` | Would exceed Owner's advance limit. | | `rail_unavailable` | No eligible rail is available. | | `compliance_hold` | Risk or compliance state blocks movement. | | `idempotency_conflict` | Idempotency key reused with different payload. | | `owner_context_mismatch` | Key, machine user, and Owner differ. | ## 14. Request flow Every agent-initiated operation starts the same way. AgentPay validates the typed input and applies the machine-user API key outside model context. Movement then authenticates the machine user, resolves the Owner and mandate, makes the authoritative policy decision, and records the request and result. The flows below show only operation-specific work.
Six-stage request flow covering request signing, validation, policy, reservation, execution, and receipts.
A Movement request passes through validation, policy, reservation, execution, and receipt stages.
### 14.1 Balance read 1. The agent calls `get_agent_balance`. 2. Movement confirms `balance.read` authority. 3. AgentPay returns the `agent` category fields allowed by policy. The proposed AgentPay tool returns the following response: ```json { "meta": { "api_request_id": "req_...", "api_request_timestamp": "2026-05-17T15:00:00Z" }, "response_type": "object", "data": { "owner_id": "d93c9b02-5b41-4f3a-91e4-43cd736dd90f", "currency": "USD", "category": "agent", "category_balance": 50000, "pending_debits": 0, "available_to_move": 50000 } } ``` ### 14.2 Agent Balance funding 1. The Owner requests consumer funding through the Owner surface. An agent can propose `movement.fund.create` for a non-consumer Receiver only under a sponsor-approved model. 2. Policy checks funding authority, caps, paykey status, bank-signal freshness, and any required balance check. 3. Movement follows the ACH top-up flow in section 10.1 and links the Charge, Bedrock transfers, Balance Transfers, and events. ### 14.3 Internal Balance transfer 1. The agent proposes `movement.transfer.create`. 2. Movement validates the source, destination, and policy or requires Movement Approval. 3. Bedrock creates the immutable transfer entries. Movement links them to the decision and events. This movement has no external rail, ACH return window, or bank-destination failure. It still requires compliance controls, an atomic ledger transaction, and an operational-error policy. ### 14.4 Agent Balance-to-paykey payout 1. The agent proposes `movement.payout.create` with a paykey token destination. 2. Policy determines eligible rails. Movement selects ACH for the MVP. 3. Bedrock creates the pending reservation. 4. The exact Bedrock-to-Payout handoff remains an open implementation decision. Any handoff must preserve the single-debit-path invariant in section 9. 5. Movement creates the Payout under the implementation selected for that boundary. A pre-submission failure voids the reservation. Timeout expiry is automatic. 6. Payment and Balance Transfer history and Movement events record later returns or reversals. Straddle's payment lifecycle distinguishes `failed` from `reversed` for current charges and payouts. `failed` occurs before funding completes. `reversed` occurs after funding completes. ([Straddle Docs][13]) The proposed orchestration must keep the following state machines separate: - `movement.status` is the mutable current view of Agent Wallet orchestration state. Original request, authorization, and evidence fields remain immutable. - `payment.status` records the current Straddle charge or payout state. - `rail.status` records a rail-specific state when needed. - Bedrock transfers are immutable records of pending, post, void, and later compensating entries. - Balance Transfer resources retain mutable status and status history. ## 15. Idempotency and retry semantics Agent Wallets should use Straddle's existing `Idempotency-Key` pattern but tighten it for ledger movements. Straddle's current idempotency behavior stores the method, path, and body hash. Identical retries replay the original response, concurrent requests return conflict, and reused keys with different payloads return conflict. ([Straddle Docs][14]) The proposed controls below apply only to identical transport retries: the same method, path, body, and idempotency key. They do not cover continuation after step-up approval. Add the following controls for Agent Wallet movements: - Store the idempotency key on the Movement. - Derive the Bedrock transfer ID only after acquiring the idempotency lock. - Return the same Movement for an identical transport retry. - Never let an identical transport retry consume a Movement Approval more than once. - Movement idempotency should outlive the current generic API window when an agent may retry during asynchronous settlement. The retention period remains an open design decision. The initial proposal is at least 30 days. For an identical transport retry, the agent repeats the same AgentPay tool call with the original typed arguments and idempotency key. The MCP extension uses the original machine-user authentication profile. Whether an approved step-up resumes the original Movement or requires a new request remains an open product decision. These retry semantics do not choose between them. ## 16. Revocation Revocation must be checked at execution time, not only at mandate issuance. ### Revocation sources - The Owner revokes the Delegation Mandate. - The Owner revokes the machine user or one of its API keys. - Straddle revokes or suspends the Customer. - Straddle blocks the paykey. - The platform suspends the embedded Account. - Straddle applies a risk or compliance hold. - A machine-user API key is compromised. ### Revocation propagation requirement Apply the following execution rule: > No movement may execute unless the Movement service verifies the current mandate status and revocation > version immediately before approval. Do not rely on long-lived mandate caches. If latency requires caching, use a short expiration and require revocation-version comparison. ### In-flight handling | State | Revocation behavior | | ---------------------------------- | -------------------------------------------------------------- | | Before policy approval | Deny immediately. | | Approved but not reserved | Deny and close request. | | Reserved but not submitted to rail | Release reservation if safe. | | Submitted to rail (`pending`) | Cannot guarantee cancellation; proceed through rail lifecycle. | | Completed | Mark audit trail with post-completion revocation. | | ACH funding pending | Stop future spends; handle the return or settlement normally. | For current Straddle charges and payouts, `pending` means Straddle has submitted the payment to the network and cannot stop, hold, or cancel it. Internal Balance movements and future card transactions require their own cancellation boundaries. ([Straddle Docs][13]) ## 17. Owner authorization UX The Owner approval experience must make plain what the Owner is delegating. ### Signing screen structure 1. **Who is being authorized** - Agent name. - Machine-user ID. - Account Owner. 2. **What the agent can do** - View the `agent` Balance. - Request Balance funding. - Pay approved destinations. - Request approval for exceptions. 3. **How much it can spend** - Per transaction. - Per day. - Per month. - Destination-specific caps. 4. **Where it can send money** - Eligible Account Balances. - paykeys. - Named vendors. - New destinations requiring approval. 5. **How funding works** - Funding paykey. - Balance check requirement. - Whether auto-replenishment is disabled or available under an approved non-consumer program. - Whether any future advance posture is contractually available. 6. **What needs approval** - Large payments. - New destinations. - Stale paykey signal. - Advance exposure above threshold, if a future advance program is enabled. - High-risk purpose. 7. **How to stop it** - Revoke mandate. - Rotate or revoke the machine-user API key. - Disable auto-funding. - Freeze machine-user movement access. ### Human-readable example > You are authorizing "Vendor Pay Agent" to use your Operations Agent Balance. It can pay approved vendors > up to $250 per payment and $1,000 per day. You can add funds from your verified Chase Checking > paykey. The agent cannot spend those funds until they reach the approved spendability threshold. > Payments above $250, new vendors, and stale bank-connection checks require your approval. You can > revoke this authorization at any time. ### UX principle Do not show rail jargon by default. Show consequences. Avoid: > ACH debit with provisional ledger credit and instant advance. For a future approved advance program, use: > Money may be available before the bank debit fully settles. The applicable agreement explains who > bears any shortfall if the debit is returned. ## 18. Machine-user provisioning UX ### Create a machine user The Owner or platform creates a machine user for one Account Owner: ```json { "name": "Vendor Pay Agent", "owner": { "type": "account", "id": "d93c9b02-5b41-4f3a-91e4-43cd736dd90f" }, "balance_category": "agent", "requested_capabilities": [ "balance.read", "movement.fund.create", "movement.transfer.create", "movement.payout.create", "movement.approval.request" ] } ``` ### Register the public key when required If the approved evidence model requires signed agent evidence, register a public key for the same machine user. It verifies evidence but does not replace API-key authentication: ```json { "machine_user_id": "musr_...", "public_key": { "kty": "OKP", "crv": "Ed25519", "x": "..." }, "use": "agent_evidence_verification" } ``` ### Issue an API key ```json { "machine_user_id": "musr_...", "name": "production", "scope": "movements" } ``` ### Owner authorization The Owner chooses the software agent, destinations, limits, and funding posture. Straddle generates the canonical Delegation Mandate, and the Owner completes the authorization ceremony. ### Rotate credentials Issue a new API key for the same machine user, move the integration, and revoke the old key after the overlap window. Both keys share one policy and budget. If registered public keys are required, retain earlier public-key records so historical evidence remains verifiable. ## 19. MCP surface Straddle publishes an official MCP server for documentation search and Code Mode. The current server does not expose AgentPay, Movement, approval, or signing tools. The proposal extends that server instead of creating another one. ([Straddle MCP][40]) The proposed AgentPay surface includes: ```text MCP tool: get_agent_balance MCP tool: create_movement MCP tool: request_owner_approval MCP tool: get_movement MCP tool: revoke_machine_user_key ``` The handler can reject malformed or locally disallowed input and collect human approval, but only Movement authorizes execution. Any AgentPay extension must validate resource-bound access tokens, authorize each tool independently, request minimum scopes, and keep the machine-user API key as a separate downstream credential. Code Mode must not provide a path around Movement policy for AgentPay operations. MCP token passthrough is prohibited. ([MCP Authorization][29], [MCP Security][30]) ## 20. Relationship to AP2 v0.2 and x402 v2 AP2 and x402 address different layers. AP2 defines authorization evidence for agent-mediated checkout. x402 defines payment negotiation, authorization payloads, verification, and settlement across transports and payment mechanisms. AP2 v0.2 is payment-method agnostic and can be composed with x402, but it does not normatively define x402 as an AP2 payment-instrument extension. AP2's FAQ describes closer alignment as ongoing. ([AP2][18], [AP2 FAQ][28]) Compatibility with either protocol is Phase 4 work, and the MVP claims neither. One boundary decision holds regardless of phase: Agent Balance funding, arbitrary payouts, and internal treasury transfers remain Straddle-native because they may have no merchant checkout object. Straddle must not encode or advertise their mandates, Movement records, or audit evidence as AP2 credentials. This boundary supports AP2 without forcing non-commerce movements into AP2's checkout model. The following table distinguishes the current proposals: | Capability | AP2 v0.2 | x402 v2 | Agent Wallet MVP | | ---------------------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------------------- | | Primary concern | Checkout authorization evidence | Payment negotiation and settlement | Delegated Balance movement | | Current artifact model | Checkout and Payment Mandates plus receipts | Scheme and network-specific payment objects | Straddle-native mandates, approvals, Movement records, and audit evidence | | Transport | Protocol-defined exchanges | HTTP, MCP, and A2A representations | Straddle MCP with proposed AgentPay tools; Movement API for approved direct integrations | | Compatibility target | AP2 adapter for qualifying checkout flows | Bedrock `exact`; existing onchain mechanism | AgentPay tools in Straddle MCP plus optional compatible protocol adapters | Appendix A defines the AP2 adapter requirements, the x402 mechanism options, and the delivery gates any compatibility claim must pass. ## 21. Proposed AgentPay and service interfaces The AgentPay, machine-user, mandate, Movement, and event interfaces below are proposed. Straddle MCP and the Balance, Balance Transfer, Charge, and Payout APIs exist today. AgentPay and `agent` do not. ### AgentPay tools in Straddle MCP Each AgentPay tool maps to one Movement operation and returns its policy, Payment, and Bedrock references. AgentPay never exposes Charge, Payout, Balance Transfer, or Bedrock writes directly. ### Underlying HTTP endpoints The proposed endpoints support AgentPay and approved direct integrations. Both paths use the same Movement enforcement. #### Existing Balance endpoints to extend ```http GET /v1/balances/current GET /v1/balance_transfers GET /v1/balance_transfers/{id} POST /v1/balance_transfers/topup POST /v1/balance_transfers/cashout ``` #### Machine users ```http POST /v1/machine_users GET /v1/machine_users/{machine_user_id} POST /v1/machine_users/{machine_user_id}/api_keys POST /v1/machine_users/{machine_user_id}/api_keys/{key_id}/revoke POST /v1/machine_users/{machine_user_id}/public_keys POST /v1/machine_users/{machine_user_id}/public_keys/{key_id}/revoke ``` #### Mandates ```http POST /v1/mandates/delegations GET /v1/mandates/{mandate_id} POST /v1/mandates/{mandate_id}/revoke POST /v1/movement_approvals POST /v1/movement_approvals/{approval_id}/approve POST /v1/movement_approvals/{approval_id}/deny ``` #### Movements ```http POST /v1/movements GET /v1/movements/{movement_id} POST /v1/movements/{movement_id}/cancel ``` #### Funding The AgentPay `create_movement` tool maps funding to Movement. Machine-user credentials do not authorize direct Charge, Payout, Balance Transfer, top-up, cash-out, or Bedrock writes. #### Movement history ```http GET /v1/movements/{movement_id}/events GET /v1/movements/{movement_id}/balance_transfers ``` ### Example AgentPay tool call The worked INV-1045 scenario assumes the `agent` category already has enough spendable funds, so it requests no top-up. The agent submits typed arguments to `create_movement`. Required agent evidence follows the signer model selected in section 8.3. This example does not assume signer custody. ```text MCP tool: create_movement ``` ```json { "operation": "movement.payout.create", "amount": 37500, "currency": "USD", "destination": { "type": "paykey_token", "token": "paykey-token-value" }, "purpose": "invoice_payment", "description": "Invoice INV-1045", "reference": "inv_1045", "idempotency_key": "op_vendor_inv_1045", "funding": { "auto_fund_if_needed": false } } ``` ### Example approved response ```json { "meta": { "api_request_id": "req_01J...", "api_request_timestamp": "2026-05-17T15:00:01Z" }, "response_type": "object", "data": { "movement_id": "mov_123", "status": "submitted", "policy_decision": { "decision": "approved", "reason": "within_delegation_mandate" }, "funding": { "triggered": false }, "payment": { "id": "5088f4bc-b3df-4d61-9274-5de69f70226d", "type": "payout", "rail": "ach", "status": "pending" }, "bedrock": { "pending_transfer_id": "bdtxn_pending_123", "resolution_transfer_id": null } } } ``` ### Example step-up response ```json { "meta": { "api_request_id": "req_01J..." }, "response_type": "object", "data": { "status": "requires_approval", "reason": "movement_approval_required", "movement_approval_id": "map_123", "approval_url": "https://dashboard.straddle.com/approvals/map_123", "expires_at": "2026-05-17T15:15:00Z" } } ``` Whether an approved step-up resumes the original Movement under the same idempotency key or requires a new request remains an open product decision. ## 22. Webhooks Agent Wallets need webhooks for developers, Owners, and platforms. ### Event types ```text machine_user.created.v1 machine_user.api_key.created.v1 machine_user.api_key.revoked.v1 machine_user.public_key.registered.v1 machine_user.public_key.revoked.v1 mandate.delegation.created.v1 mandate.delegation.revoked.v1 movement.approval.requested.v1 movement.approval.approved.v1 movement.approval.denied.v1 balance.agent.updated.v1 movement.created.v1 movement.approved.v1 movement.denied.v1 movement.submitted.v1 movement.paid.v1 movement.failed.v1 movement.reversed.v1 policy.decision.created.v1 risk.hold.created.v1 risk.hold.released.v1 ``` Public-key events apply only if the approved evidence model requires registered keys. ### Webhook payload requirements Every event carries enough linkage to resolve the underlying records: - Event fields: `event_id`, `event_type`, `created_at`, and resource version or transition time. - Request fields: `request_id` and `correlation_id`. - Authority fields when applicable: `owner_id`, `owner_type`, `balance_category`, `machine_user_id`, `public_key_id`, and `mandate_id`. - Execution fields when applicable: `movement_id`, `pending_transfer_id`, `payment_id`, `balance_transfer_ids`, and `funding_event_ids`. - `resolution_transfer_id` only when a Bedrock post or void transfer exists. Automatic expiry does not require one. Webhook delivery is asynchronous. Events may be duplicated or arrive out of order. Consumers must deduplicate on `event_id`, compare resource versions or transition times, and fetch the current resource when ordering is ambiguous. Webhook delivery is not the transaction commit point. ([Straddle Docs][33]) ## 23. Risk and reversibility ### ACH funding risk ACH debit funding can return after the agent has spent against the `agent` Balance. A late return creates advance or negative-balance exposure. Apply the following controls: - Balance check before origination. - Open-banking freshness requirement. - paykey health state. - Owner-level advance limits. - Destination risk controls. - Holds for high-risk categories. - Step-up for new destinations. - Reserve requirements. - Return-rate monitoring. - Automatic posture downgrade after return. - Machine-user freeze on unauthorized-return indicators. Straddle's status guide distinguishes bank declines, customer disputes, and ACH return codes such as R10, R11, and R29 in status sources and reason handling. Those distinctions should map directly into Agent Balance risk responses. ([Straddle Docs][13]) ### Future instant-payment risk RTP and FedNow payments are credit pushes. Network acceptance and settlement remove most of ACH's timing uncertainty, but they do not end every fraud, dispute, exception, or recovery process. Agent Wallets should record the current Payment state and later events without calling any state terminal. ([The Clearing House][16], [Federal Reserve Financial Services][12]) Apply the following controls: - Stronger pre-flight policy for instant rails. - Step-up for first-time instant destination. - Destination allowlist for human-not-present instant payouts. - No instant rail if mandate requires cheapest rail. - Hold or review for suspicious agent behavior. ### Internal Balance transfer risk Internal Bedrock transfers avoid rail return risk but still require: - Sanctions and compliance screening on both Owners. - Fraud and risk monitoring. - Velocity limits. - Purpose and destination policy. - Reversal policy for operational error. - Dispute workflow. ## 24. Compliance considerations These are design inputs for sponsor-bank and counsel review, not legal advice. ### Identity and customer due diligence The Owner must complete the applicable know-your-customer, know-your-business, and Customer Identification Program requirements through the approved Straddle Identity or Account onboarding process before Agent Balance activation. Business Owners must also complete representative and beneficial-owner checks when the program requires them. ### Anti-money-laundering and sanctions controls The approved screening and ongoing-monitoring program governs mandate creation, Balance funding, Movement execution, and destination onboarding. The program must identify the points at which policy requires screening. It must also monitor agent behavior for anomalous patterns. The program must incorporate agent-initiated payments into its 2026 Nacha fraud-monitoring processes. Controls should cover credential compromise, destination substitution, vendor impersonation, anomalous velocity, mandate changes, and entries induced through false pretenses. The responsible parties must review those processes at least annually. ([Nacha][34]) ### ACH authorization A mandate is evidence of delegated agent authority, but it is not automatically a valid ACH authorization. Before enabling Agent Balance funding, the program must classify the external account as consumer or non-consumer. It must then determine the applicable authorization type, Standard Entry Class code, Straddle `consent_type`, and evidence requirements. ([Straddle Docs][35], [Nacha][36]) For a consumer account, threshold-triggered or event-triggered replenishment is not necessarily a recurring entry because it does not occur at substantially regular intervals. It is not necessarily a Subsequent Entry under a Standing Authorization because each Subsequent Entry requires affirmative action by the Receiver. Whether an agent action under a previously signed mandate can constitute the Receiver's affirmative action requires sponsor-bank and counsel approval. For a non-consumer account, the Originator and Receiver must have an agreement that authorizes the entries and binds the Receiver to the Nacha Rules. The program must determine whether the Corporate Credit or Debit entry class is appropriate. The authorization record must identify the Receiver, Originator, account, permissible amounts or calculation method, timing or trigger, frequency classification, revocation method, and authorization channel. The system must preserve the authorization language, proof of authentication, copy provided to the Receiver, and evidence supporting every entry for the applicable retention period. Consumer authorization flows must also implement applicable advance notices, stop-payment rights, revocation handling, and internet-initiated entry security and account-validation controls. The mandate and charge record must preserve the actual authorization context. They must not substitute a generic system IP address for the Receiver's authorization evidence. ### Existing stored-value treatment The `agent` category inherits the approved Balance product's ownership, custody, FBO, liability, and sponsor-bank reconciliation treatment. It does not create a new deposit account or separate wallet liability. Existing records must continue to identify the Account Owner and reconcile top-level `total` stored value to sponsor-bank cash. Category reallocation does not change that total. The legal and regulatory review should focus on the incremental delegation behavior, including the following questions: - Whether the Account is eligible for the stored-value Balance program. - How the Owner authorizes and revokes the machine user. - How the existing disclosures describe the `agent` category and delegated movements. - How error resolution and unauthorized-transfer processes apply to agent-initiated activity. - How negative-balance recovery and returns affect the `agent` category. - Whether any future advance feature triggers additional Regulation E or Regulation Z treatment. ### Reg E / consumer protection Consumer funding sources need error-resolution, unauthorized-transfer, disclosure, and revocation flows from the beginning. Any future Customer-owned Agent Balance requires separate analysis of prepaid-account treatment under Regulation E. The program must also determine whether an advance creates a covered credit feature under Regulation Z. ([CFPB Regulation E][38], [CFPB Regulation Z][39]) ### Agent accountability The audit trail needs to answer: - Did the Owner authorize this agent? - Did the agent act within the mandate? - Did Straddle correctly evaluate policy? - Was the destination verified? - Was the funding source healthy? - Which rail was used? - What happened if the transaction failed or reversed? ## 25. Audit trail The audit trail should cryptographically link authorization evidence to execution evidence. ### Audit event chain The arrows in the following chain show evidence links to a Movement, not business-event chronology. Payment, Balance Transfer, and webhook events can arrive later or out of order. ```text owner approval ---------------------> Movement machine-user authentication --------> Movement agent evidence, when required ------> Movement policy and funding decisions -------> Movement Bedrock transfers <-----------------> Movement Payment and Balance Transfer history <-> Movement webhook delivery records <----------> Movement ``` Each audit event adds a prior hash, current hash, canonicalization and schema version, timestamp, actor, and credential version to the shared request and resource linkage defined in section 22. Store the chain in append-only, tamper-evident storage with separate access logs. Preserve the canonical bytes needed to verify every signature after key rotation. Retention, deletion holds, redaction, and reviewer access must follow the approved legal and records-management policy. ### Audit queries Support the following audit queries: ```http GET /v1/movements/{movement_id}/audit GET /v1/mandates/{mandate_id}/audit GET /v1/machine_users/{machine_user_id}/audit?from=...&to=... ``` ## 26. Product surface - **Developers and agents** see narrow tools for balance, funding, movement, approval, and status. They do not select rails or construct Payment requests. - **Owners** see authority, limits, destinations, funding posture, approval triggers, and revocation in consequence-based language. - **Operations** sees the mandate, policy reason, paykey and bank signal, funding exposure, selected rail, settlement state, and linked evidence. ## 27. MVP policy templates The MVP should offer fixed policy templates instead of a free-form policy language. Each template authorizes a fixed subset of AgentPay and Movement operations: - **Read-only agent** - Can check balance and transaction status. - Cannot fund or move money. - **Vendor payment agent** - Can pay approved paykeys. - Requires approval for a new vendor. - Enforces daily and monthly caps. - Uses ACH funding held until the approved spendability threshold. - **API spending agent** - Can pay small amounts to approved API or service providers. - Enforces a low per-transaction cap. - Permits high transaction velocity under a low monthly cap. - Requires approval for new destinations. - **Reimbursement agent** - Can reimburse approved employees or contractors. - Requires a memo and reference. - Requires step-up approval above the configured threshold. ## 28. Launch sequencing
Six-phase Agent Wallets roadmap from internal foundation through ACH wallet, risk, instant outbound, compatible surfaces, and instant inbound.
The launch sequence starts with the ACH wallet and adds risk, instant outbound, protocol compatibility, and instant inbound in later phases.
### Phase 0: Balance and delegation extension - Add the `agent` category to the existing Balance schema. - Decide how `agent` affects top-level Balance `available`. - Extend Straddle MCP with AgentPay tools backed by Movement. - Map Movement IDs to Bedrock pending transfers, any post or void transfer, and automatic expiry. - Store mandates and verify their signatures. - Manage machine-user API keys. Add registered-public-key management before write-tool launch only if the approved evidence model requires it. - Build the policy evaluator. - Link Movement records to Payments and Balance Transfers. - Link audit records to every movement. ### Phase 1: ACH-funded Agent Balance - The Owner allocates stored value to the `agent` Balance category. - The Owner links the funding paykey. - The Owner approves a Delegation Mandate. - The Receiver initiates consumer ACH top-ups through the Owner surface. An agent may initiate a non-consumer top-up only under a sponsor-approved authorization model. - AgentPay moves funds to an internal Account Balance or external paykey through Movement. - Approved direct integrations use the Movement API with the same controls. - Webhooks and the dashboard expose Agent Wallet activity. ### Phase 2: Risk posture and advance - Open-banking freshness checks. - Balance-check enforcement. - Instant advance limits. - Negative-balance workflows. - Automatic posture downgrade. - Enhanced risk monitoring. ### Phase 3: Instant outbound - RTP and FedNow payout selection where available. - Destination capability detection. - Step-up for instant first-time destinations. - Rail-aware policy. ### Phase 4: Compatible protocol surfaces - x402 v2 `exact` Bedrock mechanism, with an existing-onchain mechanism if broad ecosystem interoperability is required. - AP2 v0.2 adapter for qualifying checkout flows. - Compatibility test vectors and conformance evidence. ### Phase 5: Future inbound instant funding - Inbound push credits. - RfP support when coverage supports real product usage. - Instant inbound funding posture. ## 29. Open design decisions 1. **Funding roles.** Which party is the ACH Originator and ACH Receiver for each funding model? 2. **AP2 authorization model.** Should the adapter use an AP2 User Credential, Trusted Agent Provider, or another supported model? 3. **Straddle-native format.** Which signed JSON envelope and versioning policy should mandates and agent evidence use? 4. **Owner authorization.** Which WebAuthn credentials, recovery rules, and representative-authority checks apply? 5. **ACH authorization.** Can an autonomous agent action satisfy affirmative-action requirements for a consumer Subsequent Entry? 6. **Advance underwriting.** What inputs determine advance limits, pricing, and covered-credit treatment? 7. **RfP readiness.** What adoption threshold makes inbound RfP worth implementing? 8. **x402 integration.** Should Straddle ship the Bedrock mechanism or an existing-onchain mechanism first, and how will it resolve non-blockchain settlement identifiers upstream? 9. **Policy configuration.** Should launch use templates only, with internal configuration hidden from customers? 10. **Revocation service level.** What is the maximum acceptable propagation time? 11. **Idempotency retention.** Should movement-level idempotency persist 30, 60, or 90 days? 12. **Dispute workflow.** How do Owners dispute agent-executed payments, and what evidence is shown? 13. **Agent risk scoring.** Does Straddle score machine users separately from Owners? 14. **Destination onboarding.** Can an agent propose a new paykey destination, or only an Owner or platform user? 15. **Negative balances.** What collection, recovery, Balance restriction, and machine-user freeze process applies? 16. **Pricing.** Should pricing apply per machine user, movement, mandate, advance, or rail cost? 17. **Balance ownership and reporting.** Will a future Customer own Balance, and does the proposed `agent` category contribute to top-level `available`? 18. **Agent evidence and signer custody.** Which operations require agent evidence, who holds the private key, and how does a Straddle-hosted signer differ from proof of an external runtime? 19. **Movement Approval key binding.** Does approval bind an immutable public-key version, and how does that binding behave after rotation? 20. **Step-up resumption.** Does approval resume the original Movement under the same idempotency key or require a new request? ## Appendix A: AP2 and x402 compatibility analysis This appendix expands section 20. It defines what a credible AP2 or x402 compatibility claim requires. None of this work is part of the ACH-only MVP. ### AP2 compatibility target AP2 v0.2 defines open and closed Checkout Mandates, open and closed Payment Mandates, and separate Checkout Receipts and Payment Receipts. An AP2 Payment Mandate authorizes payment before execution. It is not a facilitator-generated transaction receipt. In the closed checkout flow, the merchant signs the Checkout JWT. The closed Checkout Mandate and Payment Mandate are cryptographically bound to that JWT. ([AP2 Specification][23]) To claim AP2 compatibility, Agent Wallets would need an AP2 v0.2 adapter for qualifying commerce flows. The adapter must accept and emit the versioned AP2 schemas, preserve role and signature requirements, bind the closed Checkout Mandate to the merchant-signed Checkout JWT, bind the Payment Mandate to that Checkout JWT, and return separate AP2 receipts. It must select an AP2 agent-authorization model and validate against the published schemas, normative verification rules, SDK tests, reference scenarios, and Straddle cross-implementation tests. Straddle must not claim certified AP2 conformance unless AP2 publishes an applicable conformance program. ### x402 compatibility target x402 v2 is an x402 Foundation open standard. Its core data model is transport-independent, with official HTTP, MCP, and Agent-to-Agent (A2A) representations. Current public mechanisms primarily use blockchain networks, but the core specification explicitly permits non-blockchain networks and encourages CAIP-2-formatted identifiers such as `ach:us` and `sepa:eu`. ([x402 v2][4], [x402 Network Support][32]) A custom HTTP `402` response or an API inspired by x402 is not x402 compatibility. To claim x402 v2 compatibility, Agent Wallets would need to implement the exact `PaymentRequired`, `PaymentPayload`, `VerifyResponse`, and `SettlementResponse` objects and the selected transport for an explicitly supported `(scheme, network)` mechanism. The simpler Straddle-native target is x402's `exact` scheme with a Bedrock network mechanism. The mechanism is protocol-conformant only if it meets three requirements. It must define a signed payment payload that binds the payer, recipient, asset, exact amount, validity window, and unique authorization. It must prevent replay. It must durably commit one atomic Bedrock Balance-to-Balance transfer. The mechanism's `SettlementResponse` would need to identify the payer and the immutable Bedrock transfer. Because the current schema describes `transaction` as a blockchain transaction hash, Straddle should confirm or contribute the non-blockchain transaction-identifier semantics upstream before claiming conformance. Every client, resource server, and Facilitator must explicitly support the Straddle `(exact, network)` mechanism, and both payer and recipient must be eligible Straddle Balance participants. That requirement limits protocol interoperability to those implementations and participants. Publishing the mechanism or adding it to an upstream SDK reduces integration work but does not make unmodified third-party sellers compatible. Interoperability with an existing seller requires the seller and its Facilitator to advertise and support the selected pair. Using an existing onchain `exact` mechanism is the most direct route only for target clients and sellers that already support that same network and asset. That path adds a digital-asset program, key custody, liquidity and reconciliation controls, sanctions and transaction monitoring, and support for the selected network and asset. An asynchronous ACH debit, ACH Payout, or provisional credit cannot represent the settled atomic Bedrock transfer. ### Compatibility delivery gates Complete the following work before claiming compatibility: 1. Publish the Straddle `exact` network mechanism, payload schema, verification rules, and settlement semantics. 2. Resolve non-blockchain `SettlementResponse.transaction` semantics with the x402 maintainers. 3. Implement the exact HTTP and MCP representations, including required HTTP headers and MCP `PaymentRequired`, `PaymentPayload`, and settlement metadata. 4. Implement the Facilitator `/verify`, `/settle`, and `/supported` contracts and ship payer, resource-server, and Facilitator test clients without exposing payer signing keys to the model. 5. Pass cross-implementation, settlement, and replay-safety tests. 6. If broader ecosystem interoperability is required, identify the target clients, sellers, and Facilitators, then implement a mechanism and network they already advertise or obtain their explicit adoption of the Bedrock mechanism. 7. Implement the AP2 v0.2 adapter and preserve AP2 credentials separately from Straddle-native artifacts. 8. Publish supported versions, upgrade policy, and conformance evidence. An onchain bridge is optional for Bedrock mechanism support and required for the existing-onchain path. Neither path is part of the ACH-only MVP. Bank and crypto settlement are both subject to applicable identity, anti-money-laundering, sanctions, fraud-monitoring, and recordkeeping obligations. Bank rails add rail-specific authorization, return, dispute, and consumer-protection rules. Blockchain settlement has different custody, finality, and transaction-monitoring requirements. Neither a mandate nor a settlement rail independently satisfies compliance obligations. ## Appendix B: Full Delegation Mandate example Section 7.1 shows the fields its discussion relies on. This example includes every proposed sub-object: velocity, destination, and purpose policy, funding policy with auto-replenishment and open-banking freshness, and issuer identification. All integer money fields use the smallest currency unit. ```json { "type": "DelegationMandate", "id": "dmd_01HZX...", "version": "2026-05-17", "issuer": { "type": "straddle", "id": "straddle" }, "subject": { "owner_type": "account", "owner_id": "d93c9b02-5b41-4f3a-91e4-43cd736dd90f", "balance_category": "agent" }, "authorized_actor": { "machine_user_id": "musr_...", "public_key_fingerprint": null }, "capabilities": [ "balance.read", "movement.fund.create", "movement.transfer.create", "movement.payout.create", "movement.approval.request" ], "spend_policy": { "currency": "USD", "max_per_transaction": 25000, "max_per_day": 100000, "max_per_month": 1000000, "velocity_window": { "max_count": 20, "window": "P1D" }, "allowed_destinations": [ { "type": "paykey_token", "token": "paykey-token-value" }, { "type": "account_balance", "account_id": "3c7a52cf-a537-48e8-91d4-c7c6f91f293c" } ], "denied_destinations": [], "purpose_allowlist": [ "vendor_payment", "invoice_payment", "api_access", "contractor_reimbursement" ], "step_up": { "required_above": 25000, "required_for_new_destination": true, "required_for_fast_finality": false } }, "funding_policy": { "permitted_inbound_methods": ["ach_debit"], "preferred_inbound_method": "ach_debit", "auto_replenishment": { "enabled": false, "threshold": 20000, "target_balance": 100000, "max_top_up": 50000 }, "risk_posture": { "mode": "hold_until_eligible", "advance_limit": 0 }, "open_banking_freshness": { "required": true, "max_age_seconds": 3600, "balance_check": "required" }, "outbound_preference": "ach" }, "validity": { "issued_at": "2026-05-17T15:00:00Z", "not_before": "2026-05-17T15:00:00Z", "expires_at": "2026-08-17T15:00:00Z" }, "revocation": { "status_endpoint": "/v1/mandates/dmd_01HZX/status", "revocation_version": 1 }, "owner_approval_evidence": { "type": "webauthn", "assertion_hash": "sha256:...", "approved_content_hash": "sha256:..." }, "straddle_signature": { "alg": "EdDSA", "kid": "straddle_signing_key_...", "value": "..." } } ``` ## References ### Straddle documentation - [Charges][2] - [Payouts][3] - [Pay by Bank][6] - [Paykeys][7] - [Bridge overview][9] - [Identity overview][10] - [Payment statuses][13] - [Idempotency][14] - [Funding][21] - [Request tracing][22] - [Webhook event catalog][33] - [ACH authorization][35] - [Straddle MCP server][40] ### Agent-commerce and security specifications - [x402 v2 specification][4], accessed 2026-08-09 - [AP2 protocol site][18], accessed 2026-08-09 - [AP2 v0.2 specification][23], accessed 2026-08-09 - [AP2 FAQ][28], accessed 2026-08-09 - [RFC 8785: JSON Canonicalization Scheme][26] - [WebAuthn Level 3][27] - [MCP authorization][29] - [MCP security guidance][30] - [x402 MCP transport][31] - [x402 network and token support][32] ### Payment-network and regulatory sources - [FedNow Service][12] - [RTP network][16] - [Visa Direct][20] - [Nacha fraud monitoring][34] - [Nacha Standing Authorization][36] - [FDIC pass-through deposit insurance][37] - [CFPB Regulation E prepaid-account definition][38] - [CFPB Regulation Z hybrid prepaid-credit cards][39] [2]: https://docs.straddle.com/guides/payments/charges "Charges: collect ACH bank payments - Straddle Docs" [3]: https://docs.straddle.com/guides/payments/payouts "Payouts: send funds to bank accounts - Straddle Docs" [4]: https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md "x402 v2 specification" [6]: https://docs.straddle.com/guides/paybybank "Pay by Bank: account-to-account payments - Straddle Docs" [7]: https://docs.straddle.com/guides/bridge/paykeys "Paykeys: secure tokens for bank payments - Straddle Docs" [9]: https://docs.straddle.com/guides/bridge/overview "Bridge API overview - Straddle Docs" [10]: https://docs.straddle.com/guides/identity/overview "Identity verification overview - Straddle Docs" [12]: https://www.frbservices.org/financial-services/fednow/about.html "About the FedNow Service | Federal Reserve Financial Services" [13]: https://docs.straddle.com/guides/payments/statuses "Payment status and lifecycle reference - Straddle Docs" [14]: https://docs.straddle.com/api-reference/idempotency "Idempotency keys for safe API retries - Straddle Docs" [16]: https://www.theclearinghouse.org/payment-systems/rtp/institution "Real Time Payments | The Clearing House" [18]: https://ap2-protocol.org/ "Agent Payments Protocol (AP2): specification and mandate model" [20]: https://developer.visa.com/capabilities/visa_direct/docs "Getting Started with Visa Direct (AFT and OCT) - Visa Developer" [21]: https://docs.straddle.com/guides/payments/funding "Payment funding and reconciliation - Straddle Docs" [22]: https://docs.straddle.com/api-reference/request-id "Request and correlation IDs - Straddle Docs" [23]: https://github.com/google-agentic-commerce/AP2/blob/main/docs/ap2/specification.md "AP2 v0.2 specification" [26]: https://www.rfc-editor.org/rfc/rfc8785.html "RFC 8785: JSON Canonicalization Scheme" [27]: https://www.w3.org/TR/webauthn-3/ "Web Authentication Level 3" [28]: https://github.com/google-agentic-commerce/AP2/blob/main/docs/faq.md "AP2 FAQ" [29]: https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization "MCP authorization specification" [30]: https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices "MCP security best practices" [31]: https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/mcp.md "x402 v2 MCP transport" [32]: https://github.com/x402-foundation/x402/blob/main/docs/core-concepts/network-and-token-support.mdx "x402 network and token support" [33]: https://docs.straddle.com/webhooks/overview/events "Straddle webhook event catalog" [34]: https://www.nacha.org/rules/risk-management-topics-fraud-monitoring-phase-2 "Nacha fraud monitoring, phase 2" [35]: https://docs.straddle.com/help/Payment-Compliance/ach-auth "Straddle ACH authorization guidance" [36]: https://www.nacha.org/rules/meaningful-modernization "Nacha Standing Authorization" [37]: https://www.fdic.gov/financial-institution-employees-guide-deposit-insurance/pass-through-deposit-insurance-coverage "FDIC pass-through deposit insurance coverage" [38]: https://www.consumerfinance.gov/rules-policy/regulations/1005/2/ "Regulation E prepaid-account definition" [39]: https://www.consumerfinance.gov/rules-policy/regulations/1026/61/ "Regulation Z hybrid prepaid-credit cards" [40]: https://github.com/straddleio/straddle-node/tree/main/packages/mcp-server "Official Straddle MCP server"