Documentation

Using Nod

Nod is an Android app that sits between an AI agent and your Solana wallet. The agent proposes a transaction, the app shows you what it really does, and nothing moves until you give your Nod.

Overview

Nod has three parts that you can run yourself:

The app (Android). Where you review and approve. It decodes and simulates every transaction on the phone, and signing happens in your own wallet over Mobile Wallet Adapter.
The backend (nod-server). A small server that passes proposals from agents to your phone and enforces the limits you set. It never holds a key that can move your funds.
The SDK (nod-sdk). What your agent uses to propose transactions. Plain HTTP works too: see the page for agents.

Prototype. Nod is open source, runs on Solana devnet by default, and has not been audited. Use test funds only.

Quick start

Install the app on an Android phone that has a fingerprint, face or screen lock set up, and a Mobile Wallet Adapter wallet such as Phantom or Solflare.
Start a backend. On a computer: npx nod-server. Add --tunnel if the phone is not on the same network (needs cloudflared or ngrok).
Point the app at it. Open Nod, enter the server address when asked, or later under Settings, Servers.
Connect your wallet. Settings, Wallet, Connect wallet, then approve in your wallet app.
Pair an agent. Agents, Show pairing code. Give the 8-character code to your agent (npx nod-sdk pair CODE --name my-agent --api URL).
Let the agent propose. Your phone buzzes with a decoded card. Hold to approve, or reject.

A tour of the app

Approvals

Proposals waiting for you, newest first, each with a countdown. Open one to see the full card.

Activity

Every proposal and what happened to it: confirmed, rejected, blocked, expired or failed. Filter by status and, when you have several agents, by agent. Entries are grouped by day.

Agents

One card per paired agent, collapsed to a summary of its limits and how many proposals it has made. Expand a card to change its limits, manage allowed recipients, freeze it, issue a new key, or remove it.

Settings

Section	What it does
Wallet	Connect or disconnect the wallet that signs.
Appearance	System, light or dark theme.
Push notifications	Shows whether notifications are on and opens Android settings if they are blocked.
Approval method	Fingerprint, face unlock or screen lock.
Servers	Add, rename, switch and delete the backends you use.
Device	The network (cluster) and the backend this app is using.
About Nod	Version, network, API version and package details.

Approving a proposal

The approval card is built on the phone from the transaction itself. It does not rely on the agent's description, or on the backend's.

Who and what: the agent's name, the amount, the recipient and the program involved.
What changes: your balance before and after, from a local simulation, plus the network fee.
Does it match? If the agent stated an intent (an amount and recipient, or swap terms), the card checks it against the real transaction. A mismatch shows a red warning and needs a deliberate press and hold.
Time: a countdown. If nobody decides in time the proposal expires and nothing is sent.

To approve, press and hold the approve button, then confirm with your fingerprint, face or screen lock. Your wallet then asks to sign. The result appears in Activity once the transaction is confirmed.

You can also reject a proposal. The agent is told, and nothing is sent.

Limits and policy

Limits are set per agent, under Agents, and are enforced before a proposal ever reaches your phone.

Setting	What it does
Auto-approve up to	Plain SOL payments under this amount, to an allowed recipient, are approved without a prompt and appear in Activity.
Hard cap per transaction	Anything over this amount is blocked automatically and the agent is told why.
Daily cap	The most an agent may send in a day.
Allowed recipients	Addresses an agent may pay without asking. A new recipient always needs you.
Freeze	While frozen, every proposal from the agent is blocked.

Whatever the limits, swaps, anything beyond plain SOL transfers, and new recipients need your Nod. Unknown programs, authority changes (token approvals, setAuthority, system assign) and amounts over the hard cap are blocked.

Auto-approved is recorded, not executed. In this version, an auto-approved proposal is marked as such, but the backend does not send the transaction itself yet.

Pairing agents

Open Agents and tap Show pairing code. The code is 8 characters, lasts 5 minutes and works once.
Give it to your agent: npx nod-sdk pair AB12CD34 --name my-agent --api https://your-backend.
The agent receives a key starting with nodk_. Keep it secret. It is shown once.

If a key leaks, tap New key on that agent's card, or Remove agent. The old key stops working immediately.

Servers

Nod works with any backend that follows its API, so you can run your own. The easiest way:

npx nod-server --tunnel

The start-up screen prints the local, LAN and (with --tunnel) public https address. Add the one your phone can reach under Settings, Servers.

Debug builds can use a plain http:// address on the same network.
Release builds require https://. Use --tunnel, or put the backend behind a proxy with a certificate.
Several servers can be saved. Switching is one tap, and Nod checks that the address really is a Nod server and a compatible version first.
Push notifications depend on the Firebase project the app was built with. A backend you run yourself still works, and the app also checks for new proposals every few seconds while it is open.

Security

Keys never enter Nod. Signing happens in your wallet over Mobile Wallet Adapter. The backend cannot sign.
The phone checks everything. It decodes and simulates the transaction itself, verifies that the transaction it signs is the one it showed you, and verifies the wallet-signed result before sending it.
Notifications are minimal. A push carries only a proposal id, never an amount, recipient or reason.
The agent is untrusted. Its reason text is display-only, and it can be frozen or removed at any time.
Backends see proposals. A backend you do not control can see the transactions agents propose. Run your own for anything sensitive.

Troubleshooting

What you see	What to try
No notification arrives	Check Settings, Push notifications and Android battery settings. Open the app: it also checks for new proposals every few seconds.
"Not a Nod server"	The address does not answer `/health` as Nod. Check the URL and port.
Release build cannot connect	Release builds only accept `https://`. Use `--tunnel` or a certificate.
Proposal expired	Nobody decided in time. Ask the agent to propose again.
The wallet asks to connect twice	Some wallets prompt again until the app's identity is verified. Approve both prompts.
A proposal was blocked	Open it in Activity and read the reason: an unknown program, an authority change, over the hard cap, or a frozen agent.

Known limitations

Prototype, not audited. Do not use with funds you cannot afford to lose.
Android only. Devnet by default.
The decoder understands a fixed set of programs (system, token, associated token, compute budget, and Jupiter swaps on mainnet). Anything else is flagged rather than interpreted.
Wallets may add compute-budget instructions before signing. Nod tolerates exactly that, with a fee cap, and nothing else.
Push delivery depends on Firebase and the phone's battery settings.

Looking for the API? See the agent instructions, which are also available as plain Markdown.