> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/guides/tool-development/tool-communication.md). # Tool Communication {% hint style="info" %} **Audience:** Nexus adopters and integrators. **Goal:** Configure and verify the HTTP and signed-message boundary between a leader and an off-chain Tool without weakening the Tool contract. {% endhint %} The `nexus-toolkit` runtime turns a `NexusTool` implementation into a plain HTTP server with `GET /health`, `GET /meta`, and `POST /invoke` endpoints. Every hop carrying signed requests must provide authenticated HTTPS; terminate TLS in the Toolkit or use an equivalently protected gateway, then point the runtime at `NEXUS_TOOLKIT_CONFIG_PATH` and feed it an allowlist of permitted leaders produced by `nexus tool auth export-allowed-leaders`. A plaintext gateway-to-Tool hop is unsafe. Signed HTTP v3 authenticates the schema-ordered canonical input hash with the Leader key. The Tool response signature then binds the response domain, that Leader signature, the deterministic invocation nonce, and the canonical response commitment. HTTPS—not the signed message—protects the HTTP method, path, query, raw transport bytes, and unsigned headers. Nexus consumes three public endpoints: * `GET /meta` advertises the FQN, schemas, timeout, and URL; * `POST /invoke` carries the signed input and returns one output variant; * `GET /health` is the readiness check that validation and orchestration use before registration. The runtime contract is intentionally small: initialize the tool implementation, bootstrap the server, keep the signing key and allowlist local, and let the CLI validate and register the endpoint. The toolkit reference documents the Rust API surface, while this guide explains the runtime behavior that operators need to run and secure a tool. #### Prerequisites * A running off-chain Tool that implements the published HTTP contract; see [Build an Off-Chain Tool](/guides/tool-development/build-offchain-tool.md). * The Tool FQN and endpoint URL. * A configured CLI identity and the authority required to register Tool communication keys. #### Illustrative request and result flow 1. Start the Tool and confirm `GET /health` returns success. 2. Confirm `GET /meta` returns the FQN, timeout, and input/output schemas that will be registered. 3. Register or rotate the Tool signing key, then export the allowed-leader data for the Tool runtime. 4. Submit one `POST /invoke` request through the normal leader path. The result must select one declared output variant and match its schema. The durable on-chain evidence is the Tool registration and its active key binding. The HTTP request and response bodies, nonces, hashes, and signatures form the transcript used when the vertex selects `RegisteredKey`; the transient request itself is not a durable object. #### Verification Use `nexus tool validate offchain --url ` to check the health and metadata surface before registration. After registration, inspect the Tool by FQN and run one bounded workflow execution. Record the Tool FQN, key id, Task or Execution ID, and result variant so a failed response can be compared with the registered schema and active key configuration. #### Common failures and recovery * **Health or metadata fails:** fix the endpoint before registration; do not register a URL whose observed schema differs from the intended Tool contract. * **Signature verification rejects a response:** check the active Leader and Tool keys, transcript nonces, body hashes, and proxy behavior. A correctly signed payload is authenticated, not independently proven semantically true. * **Output schema mismatch:** return a declared output variant or update the Tool contract through the appropriate registration/upgrade path; do not retry the same incompatible result. #### Next Continue with [Verify an Off-Chain Tool Result](/guides/tool-development/verify-offchain-tool-result.md) to choose and inspect the per-vertex verifier mode. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.talus.network/guides/tool-development/tool-communication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.