Agentic workflows

AI agents can read Nolus state and prepare actions for a user through three surfaces, and the right one depends on where the agent runs. All three share the same signing boundary, because Nolus never holds or uses the user's key and every transaction is signed by the user, either in their own wallet or on their own machine.

An agent in the user's browser tab on app.nolus.io uses WebMCP, whose tools read the connected account's balances, positions, earn and staking state and prices, open the wallet connect popup and move the user between pages without ever signing a transaction. An agent that runs anywhere that speaks HTTP uses the REST API, which reads protocol and account data and composes unsigned transactions for the user's wallet to sign. An agent on a machine with the Nolus CLI uses nolusd to query any Nolus contract and to build, sign and broadcast transactions locally with the user's key.

WebMCP

WebMCP is a proposed web standard that lets a page register tools for an agent running in the same browser. The Nolus app registers 8 tools through navigator.modelContext.registerTool, so that an agent in the tab, such as a browser extension or a built-in assistant, can inspect the user's live session and move them around the app. The agent needs no API key and no account address, because every account tool reads the account connected in the tab.

Enable WebMCP

Setting up WebMCP takes the following three steps, and the account tools need all three before they return data:

1. Use a browser that exposes navigator.modelContext. Today that means Chrome with its WebMCP early preview enabled, as WebMCP is experimental and behind a flag.
2. Open https://app.nolus.io/, which registers the 8 tools once it has booted. In a browser without navigator.modelContext the app registers nothing and reports no error, and there is no polyfill and no setting inside the app.
3. Connect a Solana wallet, Phantom or Solflare, either in the app or by having the agent call connect_wallet, because the account tools return data only after a wallet is connected.

Read tools

The read tools are marked read-only and take no arguments. When a value cannot be priced, its USD field is null, which always means that the value is unknown and never that it is zero.

Action tools

Two action tools let an agent connect the user's wallet and move the user around the app:

Without mechanism, connect_wallet reconnects the wallet used last time and fails if there is none, and in either case it signs nothing. Because navigate accepts only the listed route names, an agent cannot inject a path or query through it. An unknown mechanism or route value returns an error that names the valid values.

What WebMCP cannot do

WebMCP has no tool that signs, builds or broadcasts a transaction, so an agent cannot use it to open, repay or close a position, deposit, withdraw, stake, vote or swap. The wallet popup therefore stays the only place where a user consents to a transaction. When the user wants to act, the agent can take them to the right page with navigate and let them complete the action in the app.

REST API

The app's backend serves a public REST API at https://app.nolus.io/api/, whose contract is the OpenAPI 3.1 document at https://app.nolus.io/api/openapi.json. It offers read endpoints for prices, protocols, positions, earn pools, staking and governance, along with write endpoints that compose transactions.

The write endpoints never sign, and the backend holds no keys. Each write endpoint returns an unsigned transaction that the user's wallet signs and broadcasts. In the table below, each path after the first in a row shares the prefix of the first:

Acting for a user through the API takes four steps:

1. Read what you need, for example the user's positions or a quote.

2. Call the write endpoint with the user's Nolus account as sender. For example, POST /api/leases/open with:

   {
     "sender": "<nolus account>",
     "protocol": "SOLANA-METIS-USDC",
     "downpayment_ticker": "USDC",
     "downpayment_amount": "100000000",
     "lease_ticker": "<position asset ticker>"
   }

   Replace <nolus account> with the user's Nolus account and <position asset ticker> with the ticker of the position asset. Amounts are base units written as decimal strings. Adding max_ltd in permille caps the loan, and leaving it out gives maximum leverage.

3. Read the response, which carries the unsigned transaction, a summary of what the transaction does and the fee, the network fee that the transaction will be signed with.

4. Hand transaction to the user's wallet to sign and broadcast.

For live updates, the WebSocket at wss://app.nolus.io/ws streams price and position changes.

nolusd

Agents outside the browser use nolusd, the Nolus CLI, whose nolusd contract-help command prints every query and execute message of every Nolus contract with JSON templates. Queries run as nolusd q wasm contract-state smart <contract> '<json>' and transactions as nolusd tx wasm execute ..., or with --generate-only so that the transaction can be signed and broadcast in separate steps, and either way the keys stay on the user's machine.

To set it up, install the release binary from nolus-core releases and then point it at mainnet:

nolusd config set client chain-id pirin-1
nolusd config set client node https://rpc.nolus.network:443

Contract discovery starts from the platform admin contract nolus1gurgpv8savnfw66lckwzn4zk7fp394lpe667dhu7aw48u40lj6jsqxf8nd, which returns the contract addresses of a protocol when you query it by name:

nolusd q wasm contract-state smart nolus1gurgpv8savnfw66lckwzn4zk7fp394lpe667dhu7aw48u40lj6jsqxf8nd '{"protocol":"SOLANA-METIS-USDC"}'

The response lists the contracts of the SOLANA-METIS-USDC protocol, among them its Leaser, lending pool and oracle. The exact messages for positions and for lending are on Spot Margin and Lending.