Noxy Agent Examples

Reference implementations of autonomous agents with Noxy Human-in-the-Loop (HITL). Each example is a self-contained project you can clone, configure, and run against real APIs and (where applicable) on-chain protocols.

These examples are maintained for the official noxy-network/agent-examples repository.

Example agents

Agent	Language	Domain	What it monitors	What needs human approval
sale-trigger-agent	Python	E-commerce / marketing	Competitor sales via Tavily search	Sending a promotional email to customers
liquidation-sentinel-agent	Node.js (TypeScript)	DeFi / lending	Aave v3 health factor on Ethereum or Base	On-chain repay or supply rescue transaction
yield-rebalancer-agent	Node.js (TypeScript)	DeFi / yield	Cross-protocol lending APY via DeFiLlama	Moving funds between protocols (withdraw → supply/deposit)

Each directory has its own README, .env.example, and run instructions. Start there for agent-specific configuration, API endpoints, and demo modes.

---

What is Noxy?

Noxy Network adds human-in-the-loop decision points to autonomous agents without freezing your workflow.

When an agent reaches a decision that needs a person — approve a transaction, send an email, move funds — Noxy:

1. Delivers full context to the user on iOS, Android, Telegram, or other connected clients.
2. Keeps the agent running — no blocking wait on a single HTTP call; poll or resume when ready.
3. Encrypts payloads end-to-end with post-quantum cryptography; sensitive context is not stored in plaintext on Noxy servers.
4. Handles offline users via store-and-forward: decisions wait on the relay until the device reconnects.
5. Expires gracefully — if nobody responds within your configured TTL, the agent can treat the outcome as rejected/expired and continue.

Every agent in this repo follows the same contract: the agent proposes; the human approves on their device; only then does the agent execute the irreversible action.

---

How these examples work

All examples share a common HITL shape:

flowchart LR
    subgraph agent["Autonomous agent"]
        A[Monitor / reason] --> B{Action needed?}
        B -->|no| A
        B -->|yes| C[Build actionable decision]
    end
    C --> D[Noxy relay]
    D --> E[User device]
    E -->|approve / reject / expire| D
    D --> F[Agent receives outcome]
    F -->|approved| G[Execute action]
    F -->|rejected / expired| H[Skip or retry later]
    G --> A
    H --> A

Loading

Actionable decisions use the propose_tool_call kind: a structured payload with a tool name, args, human-readable title and summary, and optional metadata. The user sees exactly what will happen before tapping approve.

Pattern	Used by	SDK / connector
LangGraph node + bridge pause/resume	sale-trigger-agent	langgraph-noxy + noxy-sdk
Send decision + poll/wait for outcome	liquidation-sentinel-agent, yield-rebalancer-agent	@noxy-network/node-sdk

---

Noxy setup (required for all examples)

1. Create an app at noxy.network (free to start, no credit card).
2. Copy the app token — this is the bearer credential your agent runtime uses (NOXY_AUTH_TOKEN, NOXY_APP_TOKEN, etc.). It is not the app id.
3. Bind a user identity on a client device (iOS, Android, or Telegram bot) using the app id from the Noxy dashboard. Decisions are routed to that identity:
   • Web3 examples (liquidation, yield): use the wallet address as NOXY_IDENTITY_ADDRESS / identity in SDK calls (usually the same as USER_ADDRESS).
   • sale-trigger-agent: use the identity string configured in Noxy (e.g. email) as NOXY_IDENTITY_ID.
4. Choose DECISION_TTL_SECONDS / NOXY_DECISION_TTL_SECONDS — how long the user has to respond before the decision expires (shown as a countdown in the payload).

Run a quick test from your device: start an agent in demo/mock mode, confirm the decision appears, approve or reject, and verify the agent logs the expected outcome before enabling live execution.

---

Getting started

Clone the repository and open one example directory at a time. Dependencies and virtual environments are per agent, not shared at the repo root.

git clone https://github.com/noxy-network/agent-examples.git
cd agent-examples

---

Security notes

• Treat .env as secret. Never commit real EXECUTOR_PRIVATE_KEY, NOXY_AUTH_TOKEN, or API keys. Each example ships .env.example with placeholders only.
• Approve on device, every time. DeFi agents move real funds after approval. Read asset, amount, chain, and gas estimates in the Noxy payload before tapping approve.
• Use dedicated operator wallets where possible — separate monitoring (USER_ADDRESS) from execution (EXECUTOR_PRIVATE_KEY) only when you understand allowances and balances.
• Start in demo/mock mode until Noxy routing and outcome handling behave as expected.
• Tune alert hysteresis (liquidation-sentinel: REJECT_REARM_DELTA, RECOVERY_HEALTH_FACTOR) to avoid notification fatigue after rejects.
• Set conservative TTLs for time-sensitive on-chain actions; expired decisions should not execute.
• RPC and API quotas — polling intervals and external APIs (DeFiLlama, Tavily, Anthropic) have rate limits; adjust POLL_INTERVAL_MS for your environment.

These examples are educational reference code, not audited production infrastructure. Review, test on testnets or small notional, and adapt error handling and monitoring for your deployment.

---

Contributing

Contributions that add well-scoped, documented Noxy HITL examples are welcome in the noxy-network organization.

When adding or changing an example:

1. Include a standalone README with setup, env vars, run commands, and a diagram or flow description.
2. Ship .env.example with commented placeholders — no real credentials.
3. Document demo/dry-run paths so users can validate Noxy without side effects.
4. Use propose_tool_call (or documented actionable kinds) with clear title / summary for humans.

Open an issue or pull request on github.com/noxy-network/agent-examples.