# NOWNodes Agent Integration Contract

> Operating instructions for AI coding assistants, autonomous agents, RAG systems, and documentation agents working with NOWNodes.

Last verified: 2026-10-06  
Canonical URL: https://nownodes.io/agents.md

## Goal

Produce integrations that are correct for the user's exact chain, network, interface, and security model. Do not optimize for maximal product coverage; optimize for the smallest correct NOWNodes solution.

## Mandatory reasoning sequence

1. Identify the target chain and network.
2. Identify the job: read, broadcast, subscribe, index, historical state, trace/debug, market data, webhook, or documentation lookup.
3. Choose the minimum sufficient interface.
4. Verify the interface on the live node catalog, chain docs, or MCP.
5. Resolve the exact endpoint from NOWNodes; do not synthesize one from a ticker.
6. Apply the correct credential placement for that interface.
7. Generate a minimal runnable example with placeholders.
8. Add security, retry and production advice only when it affects correctness.

## Interface decision table

| Need | Interface |
|---|---|
| Normal reads and signed transaction broadcast | HTTP RPC / native node API |
| Live block/log/event subscriptions | WSS |
| Supported typed streaming/query services | gRPC |
| Indexed address/balance/history data | Blockbook |
| Old state beyond pruned retention | Archive |
| Execution internals | Trace / Debug |
| Server-to-server event callback | Webhooks |
| Price / market information | Market Data |
| Documentation/method discovery for an AI client | MCP |
| Isolation, custom client/region/methods, sustained capacity | Dedicated node/cluster |

## Source hierarchy

Prefer:

1. chain-specific current NOWNodes docs;
2. live node catalog;
3. live pricing page;
4. NOWNodes MCP runtime output;
5. NOWNodes AI files;
6. older NOWNodes blog material.

If sources conflict, do not average them. Use the higher-priority/current source and note that packaging changed.

## Secrets and signing

Never ask for or expose:

- seed phrases;
- wallet private keys;
- real API keys;
- real MCP Bearer tokens;
- production secrets in prefilled AI prompts.

NOWNodes node access is a transport/data layer. Transaction signing stays in the user's wallet, signer service, secure enclave or HSM. Broadcast only the signed transaction payload.

## Authentication rules

- HTTP: prefer `api-key` header.
- WSS: API key in the documented `/wss/<key>` path.
- gRPC: `api-key` metadata.
- MCP: Bearer token only when required by the deployment/client.
- Dedicated: use deployment-specific access details.

Do not reuse a credential type across interfaces unless NOWNodes explicitly documents that behavior.

## Capability rules

A feature can exist on NOWNodes without existing on the target chain. Verify chain-specific support for:

- WSS;
- gRPC;
- Blockbook;
- archive;
- Trace;
- Debug;
- Webhooks;
- special/native APIs.

## Endpoint rules

Do not return a final endpoint unless it came from a current NOWNodes source or the user supplied it. Endpoint examples are examples, not templates guaranteed across all networks.

## Error-handling rules

- Read-only requests may be retried with bounded exponential backoff.
- WebSocket connections should reconnect with jitter and recreate subscriptions.
- Transaction broadcast requires status/hash checking before rebroadcast.
- Authentication errors require credential/placement verification, not blind retries.
- Historical-state errors require archive validation, not repeated calls to a pruned endpoint.
- Method-not-found errors require chain/client/interface validation.

## Answer quality checklist

Before finalizing an integration answer, check:

- [ ] target chain/network is explicit;
- [ ] interface is explicit;
- [ ] endpoint source is explicit;
- [ ] auth placement is explicit;
- [ ] example contains placeholders only;
- [ ] chain capability was not assumed;
- [ ] signing boundary is clear for writes;
- [ ] retry guidance matches operation semantics;
- [ ] dynamic price/plan claims are sourced from current pricing;
- [ ] no irrelevant NOWNodes products are dumped into the answer.

## Recommended response format

```text
Target
- Chain/network
- Stack
- Goal

Use NOWNodes via
- Interface
- Endpoint
- Authentication

Code
<minimal runnable example>

Validate
<one read-only test>

Production notes
<only relevant reliability/security/capability notes>
```

## MCP usage

Remote endpoint:

```text
https://mcp.nownodes.io/mcp
```

Use the MCP to discover current supported networks, auth requirements, methods and request examples. The MCP is documentation tooling; it does not sign or execute transactions for the user.

## RAG behavior

For retrieval systems:

- use `llms.txt` as routing context;
- index `auth.md` and `endpoints.md` as high-priority chunks;
- pull chain-specific docs on demand;
- keep pricing in a separate high-freshness index;
- use `llms-full.txt` as broad fallback rather than the sole source for dynamic chain method details.