A decision API can turn outside information into a proposed wallet action. The difficult part is deciding exactly when that proposal becomes permission. Here, an oracle wallet means a wallet workflow that uses external data; it does not imply a standardized product or an autonomous trading service. A useful design lets a reviewer answer four questions: what evidence was considered, which rule applied, who authorized the action, and what actually happened. Those answers should remain distinct even when the interface makes the workflow look simple.
Begin with the action boundary
Imagine a treasury assistant that watches an approved data source and suggests moving an asset between two already approved accounts. It could return an observation, a recommendation, or a transaction proposal. These outputs carry different responsibilities. An observation reports data. A recommendation adds interpretation. A proposal specifies an action that still requires authorization. Giving all three the same response shape makes it easier for downstream software to mistake a suggestion for an instruction.
A practical API design should label those states explicitly. A response might say that evidence passed validation but execution remains blocked pending approval. It might also say that a proposal is incomplete because its destination is unknown. Avoid a single boolean named approved when that word could describe evidence quality, business policy, or signing authority. Clear states reduce ambiguity for developers and for the person reviewing the wallet screen.
Make the proposed action a bounded object
Start with an action envelope: the account, network, destination, asset identifier, maximum amount, permitted operation, and expiration. Include a unique intent identifier and the policy version used to assess it. These fields should describe the actual permitted effect, not merely the API request that happened to create it. An instruction to optimize a balance is too broad to serve as a spending boundary.
For example, a hypothetical policy might permit transferring at most ten units of a named asset to one treasury address before a specified time. The quantities in this example are illustrative. If a later quote requires eleven units or a different destination, the original proposal should become invalid. The API should generate a new proposal for review. Quietly widening the envelope after approval breaks the connection between the user's decision and the eventual transaction.
Evidence also belongs in the envelope, but as referenced observations with timestamps and identifiers. A plain sentence saying the price was checked is insufficient for later review. The decision API topic guide places this envelope within the wider wallet workflow.
Consider repeated actions as well as individual amounts
A limit per transaction is not a complete budget. In the hypothetical treasury system, many individually permitted transfers could exceed the user's intended total. Define any cumulative allowance, review period, and permitted frequency alongside the single-action limit. The component enforcing that budget should account for outstanding authorized intents, not only completed transactions, if those intents can still be executed.
Describe how the budget behaves after a restart, an uncertain submission, or a policy update. Resetting the service should not quietly reset spending authority. If accounting cannot establish how much permission remains, return an uncertain state for review. These requirements turn a broad automation preference into limits that can be inspected and tested.
Decide how data can block an action
Specify which evidence is necessary for each action. A transfer between fixed treasury accounts may need a destination check but no market prediction. A proposed exchange may need a current quote, an amount limit, and acceptable output conditions. Requiring the same evidence for every operation can create unnecessary dependencies while leaving the critical operation insufficiently checked.
Missing, stale, and conflicting evidence deserve separate outcomes. Missing means the required observation was not obtained. Stale means an observation exists but falls outside the action's allowed age. Conflicting means sources disagree under a defined comparison. Those conditions call for different investigations. None should silently become a numerical zero or an optimistic default.
Choose fallback behavior before an outage. A sensible policy for one system might preserve read access while blocking new spending. Another might permit a narrow recovery operation. The important design property is that the fallback has its own documented scope and authorization. A fallback that can expand permissions turns an operational problem into a control problem.
Keep authorization outside the recommendation
An API response cannot grant itself authority simply by returning execute as its preferred next step. Authority must come from a user or an explicitly configured permission mechanism. For Ethereum applications using typed message signatures, EIP-712 defines structured data signing and expressly leaves replay protection outside the standard. Readable fields are useful, but applications still need rules governing where, when, and how a signed instruction may be used.
For the hypothetical treasury design, bind authorization to the exact envelope and expected network. Track whether its unique intent has already been consumed. Reject expired instructions and mismatched policy versions. If a policy changes during review, require a fresh decision under the new rules. These are proposed architectural requirements; their actual enforcement depends on the wallet and contract implementation.
The approval screen should show effects in ordinary language: the asset leaving, the maximum amount, the receiving address, and any continuing permission created. A long technical payload can remain available for inspection, but it should not substitute for those consequences.
Treat simulation as conditional evidence
A simulation asks what an action would do under the state and assumptions supplied to the simulator. Use its result to identify unexpected transfers, incompatible calls, and missing permissions. Store the simulated action alongside the action proposed for signing so they can be compared. If a field changes afterward, the earlier simulation no longer describes the final proposal.
Do not express simulation success as guaranteed execution. A design should account for state changing before inclusion, unavailable infrastructure, and conflicting transactions. Include the observation time and relevant state reference in the review record. The practical question is whether the evidence is recent and relevant enough for this bounded action, rather than whether a green badge appeared at some point.
Design retries around one intent
A timeout creates uncertainty. It does not establish that an attempted transaction failed. The client may have lost a response after the service accepted the request. Automatically constructing another independent transfer in that situation can repeat the intended effect.
Use an explicit lifecycle such as proposed, authorized, submitted, included, and resolved. Add states for expired, rejected, and uncertain outcomes. A repeated API request carrying the same intent identifier should recover the existing workflow or explain why recovery is impossible. It should not casually create a second obligation. Network-specific transaction rules still matter, so application idempotency must complement the execution system rather than assume every network behaves identically.
Record what confirms completion. A submission identifier is evidence of submission, while the chosen confirmation policy determines when the workflow treats the result as settled. Keep that distinction visible to operators.
Let AI explain within the boundary
An AI component can summarize evidence, compare a proposal against a policy, and explain why review is required. It should receive only the information needed for that job. Do not place secret recovery material in prompts or logs. Keep signing authority in a separate component with narrower inputs and independently enforced limits.
External text should be treated as evidence to interpret, never as a source of new permissions. Suppose a retrieved page contains a sentence telling the assistant to change the destination account. The system should preserve it as untrusted page content and reject the resulting destination change. This is why an allowlist and amount cap need enforcement beyond the language model's explanation. The AI and LLM wallet guide explores that separation.
Review the failures before enabling execution
Test realistic negative cases: evidence arriving after expiration, a changed destination, an unknown asset scale, a duplicated request, and a successful simulation followed by a changed transaction. Check whether each produces a useful reason and a bounded next step. A generic error that encourages repeated clicking is poor operational guidance.
Finally, walk one hypothetical action from observation to completion with a person who did not design the API. They should be able to identify its evidence, limits, authorization, and outcome without guessing. If that review is difficult, simplify the contract between components before expanding automation. The related AI oracle wallet safety article provides a user-facing companion to this architectural review.
