AOMI REST APIs

Onchain execution, as a REST API.

Add swaps, yield, transfers, and settlement to an existing product with one JSON API. Aomi plans, fork-simulates, and policy-checks every transaction; the customer's wallet signs. No custody, no new signing stack.

View the API reference Integration checklist

REST + JSON · OAuth 2.1 or guest · EVM + Solana · keys stay with your signer

ContractAgent v1 · Build v2

IdempotencyEvery mutating call

NetworksEVM + Solana

Keys held by AomiZero

TWO PORTS, ONE KERNEL

Choose who plans.

Both APIs end at the same execution boundary. The difference is whether Aomi resolves a customer's intent or the platform submits the exact action its own systems selected.

AGENT V1

01 · AOMI RESOLVES THE INTENT

Agent API

Send a user's intent and wallet capabilities. Receive messages, activity, and a durable action that can be approved by the signer already inside your product.

POST /v1/agent/chatGET /v1/agent/chat/{session}POST .../actions/{action}/result

BEST FORWallets, neobanks, and conversational products

IN PRODUCTIONSommelier's liquidity assistant runs on this path.

BUILD V2

02 · YOUR SYSTEM SELECTS THE ACTION

Pipeline API

Select a catalog operation or assemble a batch directly. Receive a portable Build with ordered actions, simulation evidence, and a stable digest—with no chat session.

POST /v1/pipeline/evm/stagePOST /v1/pipeline/evm/simulatePOST /v1/pipeline/evm/commit

BEST FORTrading platforms, treasuries, and existing order flow

IN PRODUCTIONWorld Markets' Telegram trading agent keeps its own strategy and submits through this path.

THE SHARED CONTRACT

One request union, two lifecycles.

Agent chat emits revisioned Actions in its event log. Pipeline commit returns stateless ActionRequest[] without Action IDs. One confirmation UI can render the shared request union while each API keeps its own lifecycle.

Shared ActionRequest union
EVM and SVM execution envelopes
Durable Agent Actions; stateless Pipeline requests

one request renderer · two lifecycles

one call · chatraw http · illustrative wire shape

POST /v1/agent/chatAuthorization: Bearer $AOMI_TOKENIdempotency-Key: 7c1e… { "message": "Swap 0.5 ETH to USDC on Base",  "mode": "direct",  "app": "default",  "userState": { "evm": { "address": "0xAb5…", "chain_id": 8453 } } }

Actioncurrent @aomi-labs/client source contract

interface Action {  type: "action"  event_id: string  sequence: number  turn_id: string | null  occurred_at: number  id: string  revision: number  state: Action["state"]  request: ActionRequest  // execute_evm | execute_svm | sign  result?: ActionResult | null  created_at: number  expires_at: number | null}

filled by this exampleidrevisionstaterequestresult

event.request// Action event from a chat turn

Swap 0.5 ETH for ~1,240 USDC

Wrap 0.5 ETH−0.5 ETH

Swap via Uniswap v3Simulated · guards passed+1,240.18 USDC

Gas: you pay ~$1.20⚠ Price impact 2.3%

RejectApprove

approval view derived from ActionRequest and simulation evidence

Both APIs use the ActionRequest union, so the host can render the exact transactions or signing payload with simulation evidence. Agent Actions remain revisioned and recoverable; Pipeline commit requests are stateless and carry no Action ID.

TWO APIS · ONE TRANSACTION PIPELINE

Shared transaction checks, distinct state models.

The Agent API accepts customer intent and lets Aomi plan. The Pipeline API accepts the exact operation or batch your own agent, strategy, or product selected. Its portable Build crosses simulation before commit; commit returns stateless requests for the wallet to finish.

AGENT API · AOMI PLANS

Send intent.

Aomi runs the agent loop, selects tools, and turns the conversation into a durable Action.

message + wallet capabilities

PIPELINE API · YOU PLAN

Send the action.

Keep your own model, strategy, and routing logic. Submit one catalog action or an ordered batch directly.

PipelineOperationBuildInput

Both surfaces can hand the same ActionRequest union to a signerOne request renderer · one wallet binding · one evidence trail

01
Plan
Resolve the customer's intent or accept the exact action and batch the integrator selected.
Agent Actions survive the turnAgent Actions are durable and recoverable across clients; Pipeline Builds stay portable and stateless.
02
Simulate
Run the complete batch against a fork before anything reaches a signer.
Simulated before commitThe verdict and ordered balance changes travel with the simulated Build.
03
Guard
Enforce chain, signer, ordering, slippage, and application policy.
Errors fail closedTyped failures explain the next step without widening authority.
04
Sign
Return an Action request or Pipeline commit request to the wallet adapter the product already trusts.
We never hold keysThe integrator's signer remains the authority for every signature.
05
Verify
Observe the transaction and check it against the approved request before resuming.
A hash is not proofSigner, chain, calldata, ordering, and fee legs are checked onchain.

FOR AGENT ACTION RESULTSIdempotent resume

Idempotent results and ordered Action revisions make retries safe without duplicate execution or double-resuming a turn.

INSIDE THE HARNESS

An API-exposed transaction pipeline, on a harness that mutates world state.

Fundamentally, every harness that takes actions is mutating the state of the world its agent lives in — whether that world is a codebase, a file system, or a financial ledger. Aomi exposes that loop as an API: a typed action over a mutable world, judged by the world's end-state. Onchain, the world diverges at five points — a typed, gated action space, simulation as the only rehearsal, no unilateral write authority, irreversibility, and a shared, adversarial world.

Diagram comparing a coding harness loop with the Aomi harness loop. Both run intent, read, stage, verify, commit, and verify-result steps; the Aomi side marks five divergences: a typed gated tool surface, dry-run simulation as the only safe rehearsal, no harness write authority, irreversibility, and a shared adversarial world. — From AomiBench: benchmarking frontier models on onchain execution

INTEGRATION CHECKLIST

The questions engineering asks first.

Answers from the deployed Agent v1 and Pipeline Build v2 APIs. Client source can move ahead of the published npm tag, so verify the installed package version during integration.

Authentication: OAuth 2.1 access tokens (PKCE, device code, or SIWE/SIWS). Guest capability lane for attended signing, claimable into an account later.
Fail closed: A present-but-invalid credential is always 401; it never downgrades to guest. Missing scope is 403.
Idempotency: Idempotency-Key on every mutating call. Same key + same body returns the recorded response; a different body is 409.
Concurrency: One turn per session. A second request during an active turn returns 409 busy with the live cursor.
Custody models: Browser and embedded wallets sign in-band. Agent Actions stay pending until the host reports a supported result.
Verification: A reported hash moves the Action to submitted. A watcher checks signer, chain, calldata, ordering, and fee legs before completion.
Recovery: Unresolved actions appear in every delta regardless of cursor. Refresh, crash, or second device—nothing is lost.
Errors: Typed JSON errors with a retryable flag: invalid_auth, insufficient_scope, quota_exhausted, action_superseded, transaction_mismatch…

BUILD ON THE KERNEL

Start with intent. Drop down to precision when you need it.

Integrating into an existing product? Start here. Want Aomi to host the agent and the customer-facing surface too? See the Human Interface and Plugin SDK—the same signer can remain in control across every surface.

Read API documentation Talk to us