---
name: Neuro
description: Use when building applications that require trusted cross-domain interaction: identity verification, secure messaging, smart contracts, payments, and tokenized assets. Reach for this skill when integrating with the Neuron API for account management, legal identities, contract workflows, or when extending the Neuron runtime with custom packages.
metadata:
    mintlify-proj: neuro
    version: "1.0"
---

# Neuro Skill Reference

## Product summary

Neuro is a federated platform for trusted cross-domain interaction combining identity, communication, contracts, payments, and tokenized assets in a single coherent system. The **Neuron** is the core runtime — a federated server that brokers interaction between people, systems, and organizations across domain boundaries. Agents work with Neuro through two main paths: the **Neuron API** (HTTP interface for backend services) or **Neuron Development** (extending the runtime with packages). The Neuron API uses HMAC-signed requests for authentication and JWT bearer tokens for subsequent calls. Base URL: `https://{host}/Agent/` where `{host}` is your Neuron domain. Key concepts: Legal identities (verified digital actors), Smart contracts (governed digital agreements), Neuro-Ledger (distributed audit layer), eDaler (federated payments), and Neuro-Features (tokenized assets). Primary docs: https://docs.neuro-tech.io

## When to use

**Neuron API integration:** Use when building backend services that need to onboard users, manage legal identities, create/sign smart contracts, handle payments, query tokens, send secure messages, or store encrypted data. Typical tasks: account creation with email verification, applying for legal identities with cryptographic keys, proposing and signing contracts across domains, managing wallets and eDaler transactions, querying token metadata.

**Neuron Development:** Use when extending the Neuron runtime itself — writing C# packages that add new endpoints, services, or capabilities. Typical tasks: building custom modules, creating content packages, integrating third-party services, deploying smart contract templates via LegalLab.

**Neuro-Pay:** Use when integrating payment checkout, invoicing, or climate compensation services into applications.

## Quick reference

### Neuron API endpoints by capability

| Capability | Key endpoints | Use case |
|---|---|---|
| Accounts & onboarding | `Account/Create`, `Account/VerifyEMail`, `Account/Login`, `Account/Refresh` | User registration and session management |
| Authentication | `Account/Login`, `Account/Refresh`, `Account/Logout`, `Account/AuthenticateJWT` | JWT token lifecycle |
| Messaging | `Send-TextMessage`, `Send-FormattedMessage`, `Get-Roster`, `Pop-Messages` | XMPP-based secure messaging |
| Legal identities | `Legal/ApplyId`, `Legal/AddIdAttachment`, `Legal/ReadyForApproval`, `Legal/GetIdentity` | Identity verification and approval workflows |
| Contracts | `Legal/CreateContract`, `Legal/SendProposal`, `Legal/SignContract`, `Legal/GetSignedContracts` | Smart contract lifecycle |
| Wallet | `Wallet/GetBalance`, `Wallet/InitiateBuyEDaler`, `Wallet/InitiateSellEDaler` | Payment and eDaler management |
| Tokens | `Tokens/GetToken`, `Tokens/GetTokens`, `Tokens/GetTokenEvents` | Token metadata and history |
| Cryptography | `Crypto/CreateKey`, `Crypto/GetPublicKey`, `Crypto/GetAlgorithms` | Key generation and management |
| Storage | `Storage/SavePrivateXml`, `Storage/StoreInVault`, `Storage/SearchInVault` | Encrypted data persistence |

### Authentication flow

```
1. Get API key + secret from Neuron operator
2. Create nonce (unique per request)
3. Sign nonce: signature = BASE64(HMAC-SHA256(secret, nonce))
4. Call Account/Create or Account/Login with apiKey, nonce, signature
5. Receive JWT token
6. Use JWT in Authorization: Bearer {token} header for all subsequent calls
7. Refresh token before expiry with Account/Refresh
```

### Common HTTP headers

```
Authorization: Bearer {jwt_token}
Content-Type: application/json
```

### Error handling

| Status | Meaning | Action |
|---|---|---|
| 200 | Success | Proceed |
| 400 | Bad request | Check request body, nonce uniqueness, field requirements |
| 401 | Unauthorized | Verify API key, JWT validity, or HMAC signature |
| 403 | Forbidden | Check permissions or account verification status |
| 404 | Not found | Verify resource ID exists |
| 422 | Validation error | Check field types and required fields |
| 429 | Rate limited | Implement exponential backoff; check `Retry-After` header |
| 500 | Server error | Retry with exponential backoff; contact operator |

### Neuro-Pay base URL

```
https://api.neuro-admin.com
```

Authentication: `Authorization: Bearer <api_key>`

## Decision guidance

### When to use Neuron API vs Neuron Development

| Scenario | Use Neuron API | Use Neuron Development |
|---|---|---|
| Building a backend service that calls Neuro | ✓ | |
| Extending Neuron with custom C# code | | ✓ |
| Creating smart contract templates | | ✓ (via LegalLab) |
| Onboarding users to accounts | ✓ | |
| Adding new HTTP endpoints to Neuron | | ✓ |
| Querying contracts or tokens | ✓ | |
| Building a content-only package (Markdown, scripts) | | ✓ |

### When to use Account/Create vs Create-WebForm

| Approach | Use when |
|---|---|
| `Account/Create` (HMAC signed) | Building a backend service with secure credential storage |
| `Create-WebForm` | Offering browser-based signup without exposing API secrets |

### When to use Legal/ApplyId vs existing Legal Identity

| Scenario | Action |
|---|---|
| User has no legal identity yet | Call `Crypto/CreateKey`, then `Legal/ApplyId` |
| User already has approved identity | Call `Legal/GetIdentity` to retrieve it |
| Identity needs approval | Call `Legal/ReadyForApproval`, then petition review service or peers |

## Workflow

### Standard account creation and onboarding

1. **Prepare credentials** — Obtain API key and secret from Neuron operator; store securely in environment variables
2. **Create account** — Generate unique nonce, compute HMAC-SHA256 signature, call `Account/Create` with userName, email, password, apiKey, nonce, signature
3. **Handle response** — Receive initial JWT and disabled account status; store JWT temporarily
4. **Verify email** — Prompt user for verification code sent to email; call `Account/VerifyEMail` with email and code
5. **Log in** — Generate new nonce, compute signature, call `Account/Login` to receive fresh JWT for session
6. **Store JWT** — Keep JWT in memory; implement refresh logic before expiry using `Account/Refresh`

### Legal identity workflow

1. **Create cryptographic key** — Call `Crypto/CreateKey` with algorithm (e.g., RSA-4096); store returned key ID
2. **Apply for identity** — Call `Legal/ApplyId` with key ID and identity attributes (name, organization, etc.)
3. **Attach evidence** — Call `Legal/AddIdAttachment` with supporting documents (optional but recommended)
4. **Mark ready** — Call `Legal/ReadyForApproval` to signal application is complete
5. **Request approval** — Call `Legal/PetitionPeerReview` or `Legal/SelectReviewService` to route to Trust Provider or peers
6. **Verify approval** — Poll `Legal/GetIdentity` until status shows approved

### Smart contract workflow

1. **Create contract** — Call `Legal/CreateContract` with template ID, parties, and terms
2. **Propose to counterparties** — Call `Legal/SendProposal` with contract ID and recipient identities
3. **Sign contract** — Call `Legal/SignContract` with contract ID and signing key
4. **Retrieve signed contracts** — Call `Legal/GetSignedContracts` to list all signed agreements
5. **Track state** — Use `StateM/GetCurrentState` to monitor contract lifecycle

### Neuron Development package workflow

1. **Clone repositories** — Clone IoTGateway, Neuro-Ledger, IoTBroker in order to `C:/My Projects/`
2. **Build runtime** — Build and run `Waher.IoTGateway.Console` locally at `http://localhost`
3. **Create package** — Fork `NeuronExamplePackage` or create new C# project targeting `netstandard2.1`
4. **Implement module** — Create class implementing `IModule` or `IConfigurableModule` with `Start()` and `Stop()` methods
5. **Configure post-build** — Set up post-build step to install package into dev Neuron at `C:\ProgramData\IoT Gateway Dev`
6. **Test locally** — Iterate against live local Neuron; restart only for assembly packages
7. **Build for deployment** — Use `Waher.Utility.Install.exe` to create signed package manifest
8. **Deploy** — Install package on production Neuron; assembly packages require restart

## Common gotchas

- **Nonce reuse** — Every HMAC signing call requires a unique nonce. Reusing a nonce invalidates the request. Generate a new UUID or timestamp-based value each time.
- **Unverified accounts** — Accounts created via `Account/Create` are disabled until email is verified. Most endpoints return errors on unverified accounts. Always call `Account/VerifyEMail` before proceeding.
- **JWT expiry** — Tokens expire (default 3600 seconds). Implement proactive refresh using `Account/Refresh` before expiry rather than waiting for `401` errors.
- **Host mismatch in signing** — The host used in HMAC signature computation must exactly match the Neuron domain. Mismatches cause authentication failures.
- **API key vs JWT confusion** — API key + secret are used only for account creation and login (HMAC signing). JWT tokens are used for all other requests. Never send API secret in request bodies after account creation.
- **Rate limiting on auth endpoints** — `Account/Login` and `Account/Recover` are rate-limited and audited. Repeated failures can trigger temporary or permanent blocks. Implement backoff and contact operator if blocked.
- **Missing Content-Type header** — Always set `Content-Type: application/json` for POST requests. Missing headers cause parsing errors.
- **Hardcoded credentials** — Never hardcode API keys, secrets, or JWTs in source code. Use environment variables or secrets managers.
- **Assembly package restarts** — Content-only packages (Markdown, scripts) do not require restart. Assembly packages (C# `.dll` files) require Neuron restart after installation.
- **Pattern matching syntax** — Some endpoints support pattern matching with operators like `starts_with`, `contains`, `eq`. Incorrect syntax returns validation errors.
- **Deprecated endpoints** — Deprecated versions are announced 6 months before sunset. After sunset, endpoints return `410 Gone`. Monitor changelog and migrate proactively.

## Verification checklist

Before submitting work with Neuro:

- [ ] API credentials stored in environment variables, not hardcoded
- [ ] Nonce is unique for every HMAC signing call
- [ ] JWT tokens refreshed before expiry (implement proactive refresh)
- [ ] Account verified via email before using most endpoints
- [ ] Legal identity created and approved before signing contracts
- [ ] Error handling implemented for 4xx and 5xx responses
- [ ] Rate limiting respected with exponential backoff on `429` responses
- [ ] HTTPS/TLS used for all requests (no plain HTTP)
- [ ] Content-Type header set to `application/json` for POST requests
- [ ] Authorization header includes `Bearer {token}` format
- [ ] Sensitive data (keys, tokens, secrets) not logged
- [ ] Package manifest includes all files for Neuron Development packages
- [ ] Post-build step configured correctly for local dev Neuron installation
- [ ] Assembly packages tested with Neuron restart

## Resources

**Comprehensive navigation:** https://docs.neuro-tech.io/llms.txt

**Critical documentation pages:**
- [Neuron API Introduction](/neuron-api/introduction) — Overview of API capabilities and structure
- [Authentication](/neuron-api/authentication) — HMAC signing and JWT token lifecycle
- [Creating an account](/neuron-api/guides/creating-an-account) — Step-by-step account creation and verification

---

> For additional documentation and navigation, see: https://docs.neuro-tech.io/llms.txt