NIP-A5: Agent Service Agreements#2273
Open
refined-element wants to merge 2 commits intonostr-protocol:masterfrom
Open
NIP-A5: Agent Service Agreements#2273refined-element wants to merge 2 commits intonostr-protocol:masterfrom
refined-element wants to merge 2 commits intonostr-protocol:masterfrom
Conversation
Four addressable event kinds (38400-38403) for agent-to-agent service discovery, negotiation, settlement, and reputation on Nostr. - Kind 38400: Capability Advertisement - Kind 38401: Service Request - Kind 38402: Service Agreement - Kind 38403: Attestation Settlement via L402 (HTTP 402 + Lightning), negotiation via encrypted DMs (NIP-17), reputation via on-protocol attestations with payment proof. Implementations: Python/TypeScript/.NET SDKs, live relay with 24 capabilities, MCP server with 6 ASA tools.
There was a problem hiding this comment.
Pull request overview
Adds a new draft NIP (NIP-A5) specifying “Agent Service Agreements” (ASAs): four new addressable event kinds for agent capability discovery, service requests, bilateral agreements, and post-completion attestations, plus README indexing updates so the new NIP/kinds/tags are discoverable within the repo.
Changes:
- Add new NIP document A5.md defining kinds 38400–38403 and associated tags/flows (discovery, negotiation, settlement, reputation).
- Update README.md to link NIP-A5 and register the new event kinds in the global kinds table.
- Extend README.md “Common Tags” registry with ASA-related tags (e.g.,
budget,l402,negotiable,proof,rating,status,terms) and update the meaning ofs.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 9 comments.
| File | Description |
|---|---|
| README.md | Adds NIP-A5 link, registers kinds 38400–38403, and updates common tag registry for ASA tags. |
| A5.md | Introduces the full NIP-A5 specification: event kinds, tag schemas, discovery/negotiation/settlement, and security considerations. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
A5.md
Outdated
Comment on lines
+52
to
+54
| | `schema` | no | URL to JSON Schema or OpenAPI spec | | ||
| | `capacity` | no | `["capacity", "<amount>", "<unit>"]` -- e.g. `["capacity", "100", "requests/hour"]` | | ||
| | `uptime` | no | Self-reported uptime ratio (e.g. `"0.997"`) | |
Comment on lines
112
to
114
| - [NIP-C7: Chats](C7.md) | ||
| - [NIP-A5: Agent Service Agreements](A5.md) | ||
| - [NIP-EE: E2EE Messaging using MLS Protocol](EE.md) --- **unrecommended**: superseded by the [Marmot Protocol](https://github.com/marmot-protocol/marmot) |
A5.md
Outdated
| | `l402` | no | L402-protected endpoint URL for service delivery | | ||
| | `terms` | yes | `["terms", "<type>", "<value>", "<unit>"]` -- see terms types below | | ||
| | `status` | yes | One of: `"proposed"`, `"active"`, `"completed"`, `"disputed"`, `"expired"` | | ||
| | `expiry` | no | Unix timestamp for automatic expiration | |
Comment on lines
+206
to
+209
| | `L` | yes | `["L", "nostr.agent.attestation"]` | | ||
| | `l` | yes | `["l", "completed", "nostr.agent.attestation"]` | | ||
| | `proof` | no | Hash of L402 payment preimage, proving a real transaction occurred | | ||
|
|
Comment on lines
+104
to
+108
| | `d` | yes | Unique request identifier | | ||
| | `s` | yes | Service category (multiple allowed) | | ||
| | `budget` | no | `["budget", "<amount>", "<unit>"]` | | ||
| | `deadline` | no | `["deadline", "<unix-timestamp>"]` | | ||
| | `t` | no | Hashtag for discovery (multiple allowed) | |
A5.md
Outdated
|
|
||
| ### Agent Activity Posts (Optional) | ||
|
|
||
| Agents MAY publish kind 1 text notes ([NIP-01](01.md)) with an `agent` tag for human-readable status updates. |
A5.md
Outdated
| | `capacity` | no | `["capacity", "<amount>", "<unit>"]` -- e.g. `["capacity", "100", "requests/hour"]` | | ||
| | `uptime` | no | Self-reported uptime ratio (e.g. `"0.997"`) | | ||
| | `t` | no | Hashtag for discovery (multiple allowed) | | ||
| | `negotiable` | no | `"true"`, `"false"`, or `["negotiable", "floor", "<amount>"]` | |
A5.md
Outdated
| |-----|----------|-------------| | ||
| | `d` | yes | Unique service identifier | | ||
| | `s` | yes | Service category (multiple allowed) | | ||
| | `price` | yes | `["price", "<amount>", "<unit>", "<model>"]` -- e.g. `["price", "50", "sats", "per-request"]` | |
A5.md
Outdated
Comment on lines
+50
to
+54
| | `l402` | no | L402-protected endpoint URL | | ||
| | `endpoint` | no | `["endpoint", "<url>", "<method>"]` -- API endpoint | | ||
| | `schema` | no | URL to JSON Schema or OpenAPI spec | | ||
| | `capacity` | no | `["capacity", "<amount>", "<unit>"]` -- e.g. `["capacity", "100", "requests/hour"]` | | ||
| | `uptime` | no | Self-reported uptime ratio (e.g. `"0.997"`) | |
- Specify all tag formats as explicit arrays (l402, schema, uptime, negotiable) - Reuse NIP-40 `expiration` tag instead of custom `expiry` - Align `price` tag with NIP-99 terminology (number/currency/frequency) - Specify `proof` as Lightning payment_hash (SHA-256 of preimage, 64-char hex) - Add missing tags to README Common Tags (capacity, deadline, endpoint, schema, uptime) - Move NIP-A5 to correct alphabetical position in README list (after A4, before B0) - Mark `agent` tag as ASA-specific, not globally reserved
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Four new addressable event kinds (38400–38403) for agent-to-agent service discovery, negotiation, settlement, and reputation on Nostr.
Core design:
#s,#ttags)prooftag)Relationship to existing NIPs:
Implementations
This NIP is implemented and live:
wss://agents.lightningenable.com— 24 capabilities published and queryableAll three SDKs have CI/CD via GitHub Actions and are published to their respective package registries.
Why this matters
AI agents need to discover, negotiate with, and pay other agents. Today this requires centralized API marketplaces. ASAs put the coordination layer on Nostr (decentralized identity + discovery) and the settlement layer on Lightning (instant, atomic payments via L402). No platform intermediary needed.