@jonathanbulkeley/plugin-mycelia-signal 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +133 -114
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,190 +1,209 @@
1
- # @elizaos/plugin-mycelia-signal
1
+ # @jonathanbulkeley/plugin-mycelia-signal
2
2
 
3
- Mycelia Signal sovereign price oracle plugin for ElizaOS.
3
+ **Mycelia Signal sovereign price oracle plugin for ElizaOS.**
4
4
 
5
- Provides cryptographically signed price attestations for BTC, ETH, SOL, XAU, and EUR pairs. Every response is a canonical signed payload — pair, price, sources, aggregation method, timestamp, and nonce — independently verifiable against a known public key. No vendor trust required.
5
+ 56 endpoints covering crypto pairs, FX rates, economic indicators, and commodities. Every response is cryptographically signed and independently verifiable. No API keys. No accounts. Pay per query via Lightning (L402) or USDC on Base (x402).
6
6
 
7
- **Payment options:**
8
- - **L402** — pay per query in Bitcoin sats via Lightning Network
9
- - **x402** — pay per query in USDC on Base
7
+ [![npm version](https://img.shields.io/npm/v/@jonathanbulkeley/plugin-mycelia-signal.svg)](https://www.npmjs.com/package/@jonathanbulkeley/plugin-mycelia-signal)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
10
9
 
11
- No API keys. No subscriptions. No accounts.
10
+ ---
11
+
12
+ ## What is Mycelia Signal?
13
+
14
+ Mycelia Signal is a sovereign oracle — a price and data attestation service that signs every response with a cryptographic key. Agents and applications can verify that data came from Mycelia Signal and has not been tampered with, without trusting any intermediary.
15
+
16
+ - **L402 (Lightning):** Pay in sats. secp256k1 ECDSA signatures. Bitcoin-native.
17
+ - **x402 (USDC on Base):** Pay in USDC. Ed25519 signatures. EVM-native.
18
+ - **56 endpoints:** Crypto, FX, economic indicators, commodities.
19
+ - **Preview mode:** Append `/preview` to any endpoint for free unsigned sample data.
20
+
21
+ Docs: [myceliasignal.com/docs](https://myceliasignal.com/docs)
12
22
 
13
23
  ---
14
24
 
15
- ## Supported Pairs
16
-
17
- | Pair | Description | Cost (L402) | Cost (x402) |
18
- |------|-------------|-------------|-------------|
19
- | BTC/USD | Bitcoin / US Dollar spot | 10 sats | $0.001 |
20
- | BTC/USD VWAP | Bitcoin / US Dollar 5-min VWAP | 20 sats | $0.002 |
21
- | ETH/USD | Ethereum / US Dollar spot | 10 sats | $0.001 |
22
- | EUR/USD | Euro / US Dollar spot | 10 sats | $0.001 |
23
- | XAU/USD | Gold / US Dollar spot | 10 sats | $0.001 |
24
- | SOL/USD | Solana / US Dollar spot | 10 sats | $0.001 |
25
- | BTC/EUR | Bitcoin / Euro spot | 10 sats | $0.001 |
26
- | BTC/EUR VWAP | Bitcoin / Euro 5-min VWAP | 20 sats | $0.002 |
27
- | ETH/EUR | Ethereum / Euro spot | 10 sats | $0.001 |
28
- | SOL/EUR | Solana / Euro spot | 10 sats | $0.001 |
29
- | XAU/EUR | Gold / Euro spot | 10 sats | $0.001 |
25
+ ## Endpoints
26
+
27
+ ### Crypto Pairs (18 pairs including VWAP)
28
+ BTC/USD, BTC/EUR, BTC/JPY (spot + VWAP), ETH/USD, ETH/EUR, ETH/JPY, SOL/USD, SOL/EUR, SOL/JPY, XRP/USD, ADA/USD, DOGE/USD
29
+
30
+ ### Precious Metals (3 pairs)
31
+ XAU/USD, XAU/EUR, XAU/JPY
32
+
33
+ ### FX Rates (16 pairs)
34
+ EUR/USD, EUR/JPY, EUR/GBP, EUR/CHF, EUR/CNY, EUR/CAD, GBP/USD, GBP/JPY, GBP/CHF, GBP/CNY, GBP/CAD, USD/JPY, USD/CHF, USD/CNY, USD/CAD, CHF/JPY, CHF/CAD, CNY/JPY, CNY/CAD, CAD/JPY
35
+
36
+ ### US Economic Indicators (8 indicators)
37
+ CPI, CPI Core, Unemployment Rate, Nonfarm Payrolls, Fed Funds Rate, GDP, PCE, Yield Curve
38
+
39
+ ### EU Economic Indicators (6 indicators)
40
+ HICP, HICP Core, HICP Services, Unemployment Rate, GDP, Employment
41
+
42
+ ### Commodities (5 indicators)
43
+ WTI Crude, Brent Crude, Natural Gas, Copper, US Dollar Index (DXY)
44
+
45
+ ### Pricing
46
+ | Category | x402 (USDC) | L402 (sats) |
47
+ |----------|-------------|-------------|
48
+ | Price pairs & FX | $0.01 | 10 sats |
49
+ | VWAP pairs | $0.02 | 20 sats |
50
+ | Economic indicators | $0.10 | 1000 sats |
51
+ | Commodities | $0.10 | 1000 sats |
30
52
 
31
53
  ---
32
54
 
33
55
  ## Installation
34
56
 
35
57
  ```bash
36
- npm install @elizaos/plugin-mycelia-signal
58
+ npm install @jonathanbulkeley/plugin-mycelia-signal
37
59
  ```
38
60
 
39
61
  ---
40
62
 
41
63
  ## Usage
42
64
 
43
- ### Basic (no payment — free endpoints only)
44
-
45
- ```typescript
46
- import { myceliaSignalPlugin } from "@elizaos/plugin-mycelia-signal";
47
-
48
- // In your agent character config:
49
- {
50
- plugins: [myceliaSignalPlugin]
51
- }
52
- ```
65
+ ### Free mode (preview data — no payment required)
53
66
 
54
- ### With x402 (USDC on Base)
67
+ The plugin works out of the box with no configuration. Agents can query any supported pair using natural language. Without a payment handler configured, the plugin fetches free unsigned preview data (up to 5 minutes stale).
55
68
 
56
69
  ```typescript
57
- import { createMyceliaSignalPlugin } from "@elizaos/plugin-mycelia-signal";
70
+ import { myceliaSignalPlugin } from '@jonathanbulkeley/plugin-mycelia-signal';
58
71
 
59
- const plugin = createMyceliaSignalPlugin({
60
- x402PaymentHandler: async (paymentDetails) => {
61
- // Use Coinbase AgentKit, Viem, or any EVM wallet to pay USDC on Base
62
- // Returns the X-Payment header value
63
- const payment = await yourWallet.payX402(paymentDetails);
64
- return payment.header;
65
- }
72
+ const agent = new AgentRuntime({
73
+ plugins: [myceliaSignalPlugin],
74
+ // ... other config
66
75
  });
67
76
  ```
68
77
 
69
- ### With L402 (Lightning)
78
+ ### Paid mode — L402 (Lightning)
79
+
80
+ Configure a Lightning payment handler to receive signed attestations:
70
81
 
71
82
  ```typescript
72
- import { createMyceliaSignalPlugin } from "@elizaos/plugin-mycelia-signal";
83
+ import { createMyceliaSignalPlugin } from '@jonathanbulkeley/plugin-mycelia-signal';
73
84
 
74
85
  const plugin = createMyceliaSignalPlugin({
75
- preferL402: true,
76
- lightningMacaroon: "your-macaroon",
77
- lightningPreimageFetcher: async (invoice) => {
78
- // Use your Lightning wallet SDK to pay the invoice
79
- // Returns the payment preimage
80
- const result = await yourLightningWallet.payInvoice(invoice);
81
- return result.preimage;
82
- }
86
+ lightningPreimageFetcher: async (invoice: string) => {
87
+ // Pay the invoice with your Lightning node/wallet and return the preimage
88
+ const preimage = await yourLightningNode.payInvoice(invoice);
89
+ return preimage;
90
+ },
83
91
  });
84
92
  ```
85
93
 
86
- ### With Coinbase AgentKit (recommended for AI agents)
94
+ ### Paid mode — x402 (USDC on Base)
87
95
 
88
96
  ```typescript
89
- import { createMyceliaSignalPlugin } from "@elizaos/plugin-mycelia-signal";
90
- import { CdpWalletProvider } from "@coinbase/agentkit";
91
-
92
- // AgentKit wallet on Base — pays x402 natively
93
- const walletProvider = await CdpWalletProvider.configureWithWallet({ /* ... */ });
97
+ import { createMyceliaSignalPlugin } from '@jonathanbulkeley/plugin-mycelia-signal';
94
98
 
95
99
  const plugin = createMyceliaSignalPlugin({
96
- x402PaymentHandler: async (paymentDetails) => {
97
- // AgentKit handles x402 payment automatically
98
- return await walletProvider.payX402(paymentDetails);
99
- }
100
+ x402PaymentHandler: async (paymentDetails: unknown) => {
101
+ // Sign and submit the USDC transfer on Base, return the X-Payment header value
102
+ const header = await yourWallet.signX402Payment(paymentDetails);
103
+ return header;
104
+ },
100
105
  });
101
106
  ```
102
107
 
103
108
  ---
104
109
 
105
- ## Agent Actions
110
+ ## Example Queries
106
111
 
107
- Once installed, your ElizaOS agent will respond to natural language queries about prices:
112
+ Agents respond to natural language. Examples:
108
113
 
109
- - *"What's the Bitcoin price?"* → fetches BTC/USD signed attestation
110
- - *"Get me the ETH USD price"* → fetches ETH/USD signed attestation
111
- - *"What's gold trading at?"* → fetches XAU/USD signed attestation
112
- - *"SOL price in euros"* → fetches SOL/EUR signed attestation
113
- - *"BTC VWAP"* → fetches BTC/USD 5-minute VWAP attestation
114
-
115
- Each response includes:
116
- - Current price
117
- - UTC timestamp
118
- - Sources used (exchange names)
119
- - Aggregation method (median or VWAP)
120
- - Cryptographic signature for independent verification
121
- - Public key reference
114
+ - *"What's the Bitcoin price?"*
115
+ - *"Get me the BTC/USD VWAP"*
116
+ - *"What's the current EUR/USD rate?"*
117
+ - *"What's the gold price in USD?"*
118
+ - *"What's US CPI?"*
119
+ - *"Get the Fed Funds Rate"*
120
+ - *"What's the WTI crude oil price?"*
121
+ - *"What's the DXY?"*
122
122
 
123
123
  ---
124
124
 
125
125
  ## Response Format
126
126
 
127
- The plugin returns structured content alongside the natural language response:
127
+ Every paid response includes a signed canonical attestation:
128
128
 
129
129
  ```json
130
130
  {
131
- "pair": "BTCUSD",
132
- "price": "67125.10",
133
- "currency": "USD",
134
- "timestamp": "2026-03-05T14:07:07Z",
135
- "sources": ["binance", "bitstamp", "coinbase", "gemini", "kraken"],
136
- "method": "median",
137
- "signature": "<base64>",
138
- "pubkey": "<hex>",
139
- "canonical": "v1|BTCUSD|67125.10|USD|2|2026-03-05T14:07:07Z|890123|binance,bitstamp,coinbase,gemini,kraken|median"
131
+ "domain": "BTCUSD",
132
+ "canonical": "v1|PRICE|BTCUSD|84231.50|USD|2|binance,bitstamp,coinbase,kraken,...|median|1741514400|482910",
133
+ "signature": "<base64-encoded-signature>",
134
+ "pubkey": "<public-key-hex>",
135
+ "signing_scheme": "secp256k1_ecdsa"
140
136
  }
141
137
  ```
142
138
 
143
- The `canonical` field is the exact string that was signed. To verify independently:
139
+ The `canonical` string is the signed payload. Verify it independently using the public key at [myceliasignal.com/docs/keys](https://myceliasignal.com/docs/keys).
140
+
141
+ ### Canonical Format
142
+ ```
143
+ v1|PRICE|PAIR|PRICE|CURRENCY|DECIMALS|SOURCES|METHOD|TIMESTAMP|NONCE
144
+ ```
145
+
146
+ See [Canonical Format docs](https://myceliasignal.com/docs/canonical-format) for full specification.
147
+
148
+ ---
149
+
150
+ ## Signature Verification
151
+
152
+ ### L402 (secp256k1 ECDSA) — Python
144
153
 
145
154
  ```python
146
- import base64, hashlib
155
+ import hashlib, base64
147
156
  from coincurve import PublicKey
148
157
 
149
- canonical = "v1|BTCUSD|67125.10|..."
150
- signature_b64 = "<signature from response>"
151
- pubkey_hex = "<pubkey from response>"
152
-
153
- msg_hash = hashlib.sha256(canonical.encode()).digest()
154
- pub = PublicKey(bytes.fromhex(pubkey_hex))
155
- sig = base64.b64decode(signature_b64)
156
- valid = pub.verify(sig, msg_hash, hasher=None)
158
+ def verify_l402(response: dict) -> bool:
159
+ msg_hash = hashlib.sha256(response["canonical"].encode()).digest()
160
+ pubkey = PublicKey(bytes.fromhex(response["pubkey"]))
161
+ return pubkey.verify(base64.b64decode(response["signature"]), msg_hash, hasher=None)
157
162
  ```
158
163
 
159
- Full verification guide: https://myceliasignal.com/docs/verification
164
+ ### x402 (Ed25519) — Python
160
165
 
161
- ---
162
-
163
- ## Payment Protocols
166
+ ```python
167
+ import hashlib, base64
168
+ from nacl.signing import VerifyKey
169
+ from nacl.encoding import RawEncoder
170
+
171
+ def verify_x402(response: dict) -> bool:
172
+ msg_hash = hashlib.sha256(response["canonical"].encode()).digest()
173
+ vk = VerifyKey(bytes.fromhex(response["pubkey"]), encoder=RawEncoder)
174
+ try:
175
+ vk.verify(msg_hash, base64.b64decode(response["signature"]))
176
+ return True
177
+ except Exception:
178
+ return False
179
+ ```
164
180
 
165
- ### x402 (USDC on Base) — recommended for AI agents
181
+ Full verification guide: [myceliasignal.com/docs/verification](https://myceliasignal.com/docs/verification)
166
182
 
167
- The x402 protocol is purpose-built for machine-to-machine payments. The agent pays USDC on Base Mainnet and receives the signed attestation in the same HTTP exchange. Compatible with Coinbase AgentKit Agentic Wallets.
183
+ ---
168
184
 
169
- - Asset: USDC on Base (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)
170
- - Docs: https://myceliasignal.com/docs/x402
185
+ ## Public Keys
171
186
 
172
- ### L402 (Lightning Network) — for Bitcoin-native agents
187
+ Each GC node uses its own per-instance keypair:
173
188
 
174
- The L402 protocol uses HTTP 402 with a Lightning invoice and macaroon. Pay the invoice, extract the preimage, resend the request.
189
+ | Node | Protocol | Public Key |
190
+ |------|----------|------------|
191
+ | US GC | L402 (secp256k1) | `03c1955b8c543494c4ecd86d167105bcc7ca9a91b8e06cb9d6601f2f55a89abfbf` |
192
+ | Asia GC | L402 (secp256k1) | `02b1377c30c7dcfcba428cf299c18782856a12eb4fab32b87081460f4ba2deab73` |
193
+ | US GC | x402 (Ed25519) | `f4f0e52b5f7b54831f965632bf1ebf72769beda4c4e3d36a593f7729ec812615` |
194
+ | Asia GC | x402 (Ed25519) | `7ab07fbe7d08cd16823e5eb0db0e21f3f38e9366d5fd00d14e95df0fb9b51a1a` |
175
195
 
176
- - Cost: 10–20 sats per query
177
- - Docs: https://myceliasignal.com/docs/l402
196
+ Full public keys page: [myceliasignal.com/docs/keys](https://myceliasignal.com/docs/keys)
178
197
 
179
198
  ---
180
199
 
181
200
  ## Links
182
201
 
183
- - **Documentation:** https://myceliasignal.com/docs
184
- - **API Reference:** https://myceliasignal.com/openapi.json
185
- - **Public Keys:** https://myceliasignal.com/docs/keys
186
- - **GitHub:** https://github.com/jonathanbulkeley/mycelia-signal-sovereign-oracle
187
- - **Support:** info@myceliasignal.com
202
+ - **Website:** [myceliasignal.com](https://myceliasignal.com)
203
+ - **Docs:** [myceliasignal.com/docs](https://myceliasignal.com/docs)
204
+ - **npm:** [npmjs.com/package/@jonathanbulkeley/plugin-mycelia-signal](https://www.npmjs.com/package/@jonathanbulkeley/plugin-mycelia-signal)
205
+ - **GitHub:** [github.com/jonathanbulkeley/elizaos-plugin-mycelia-signal](https://github.com/jonathanbulkeley/elizaos-plugin-mycelia-signal)
206
+ - **API:** [api.myceliasignal.com](https://api.myceliasignal.com)
188
207
 
189
208
  ---
190
209
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jonathanbulkeley/plugin-mycelia-signal",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
4
  "description": "Mycelia Signal sovereign oracle plugin for ElizaOS — 56 endpoints covering crypto pairs, FX rates, economic indicators, and commodities. Cryptographically signed attestations via Lightning (L402) or USDC on Base (x402)",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",