@agentbadge/hedera-core 0.1.15

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.
@@ -0,0 +1,13 @@
1
+ export interface TierEntry {
2
+ name: string;
3
+ price: number;
4
+ capabilities: string[];
5
+ }
6
+ export declare function getCatalog(): TierEntry[];
7
+ export interface McpToolEntry {
8
+ name: string;
9
+ description: string;
10
+ category: "passport" | "directory" | "market" | "a2a" | "auth" | "audit" | "discovery" | "guide";
11
+ }
12
+ export declare const MCP_TOOLS_INDEX: McpToolEntry[];
13
+ export declare function getLlmsTxt(): string;
@@ -0,0 +1,231 @@
1
+ const CATALOG = [
2
+ {
3
+ name: "bronze",
4
+ price: 10,
5
+ capabilities: ["api_call", "payment"],
6
+ },
7
+ {
8
+ name: "silver",
9
+ price: 50,
10
+ capabilities: ["api_call", "payment", "data_provide"],
11
+ },
12
+ {
13
+ name: "gold",
14
+ price: 200,
15
+ capabilities: ["api_call", "payment", "data_provide", "verified", "marketplace"],
16
+ },
17
+ {
18
+ name: "platinum",
19
+ price: 500,
20
+ capabilities: [
21
+ "api_call",
22
+ "payment",
23
+ "data_provide",
24
+ "verified",
25
+ "marketplace",
26
+ "multi_agent",
27
+ "governance",
28
+ ],
29
+ },
30
+ ];
31
+ export function getCatalog() {
32
+ return CATALOG.map((t) => ({ ...t, capabilities: [...t.capabilities] }));
33
+ }
34
+ export const MCP_TOOLS_INDEX = [
35
+ { name: "request_passport", description: "Issue a new agent passport NFT (x402 payment)", category: "passport" },
36
+ { name: "upload_image", description: "Upload image to IPFS, return ipfs:// URI", category: "passport" },
37
+ { name: "verify_passport", description: "Verify passport on-chain status", category: "passport" },
38
+ { name: "get_passport", description: "Get passport metadata", category: "passport" },
39
+ { name: "list_passports", description: "List all issued passports", category: "passport" },
40
+ { name: "upgrade_tier", description: "Upgrade passport tier", category: "passport" },
41
+ { name: "revoke_passport", description: "Revoke passport (admin)", category: "passport" },
42
+ { name: "get_audit_trail", description: "Get audit events for a passport", category: "audit" },
43
+ { name: "get_tier_requirements", description: "Get tier catalog with pricing", category: "audit" },
44
+ { name: "register_agent", description: "Register agent in HCS directory", category: "directory" },
45
+ { name: "find_agents", description: "Find agents by capability", category: "directory" },
46
+ { name: "send_message", description: "Send A2A message (server-key)", category: "a2a" },
47
+ { name: "send_message_with_key", description: "Send agent-signed A2A message", category: "a2a" },
48
+ { name: "get_inbox", description: "Get agent inbox messages", category: "a2a" },
49
+ { name: "get_conversation", description: "Get conversation between two agents", category: "a2a" },
50
+ { name: "post_task", description: "Post marketplace task", category: "market" },
51
+ { name: "list_tasks", description: "List marketplace tasks", category: "market" },
52
+ { name: "claim_task", description: "Claim a marketplace task", category: "market" },
53
+ { name: "deliver_result", description: "Deliver task results", category: "market" },
54
+ { name: "prepare_payment", description: "Prepare frozen payment for offline signing", category: "market" },
55
+ { name: "complete_task", description: "Complete task with P2P HBAR payment", category: "market" },
56
+ { name: "sign_transaction", description: "Sign frozen Hedera transaction bytes", category: "auth" },
57
+ { name: "complete_task_with_key", description: "Complete task with agent key (convenience)", category: "market" },
58
+ { name: "post_task_with_key", description: "Post task with agent-signed HCS", category: "market" },
59
+ { name: "claim_task_with_key", description: "Claim task with agent-signed HCS", category: "market" },
60
+ { name: "deliver_result_with_key", description: "Deliver result with agent-signed HCS", category: "market" },
61
+ { name: "get_guide", description: "Fetch a skill guide as markdown", category: "guide" },
62
+ { name: "list_guides", description: "List available skill guides", category: "guide" },
63
+ { name: "get_agent_card", description: "Fetch server Agent Card", category: "discovery" },
64
+ { name: "search_agents", description: "Search agents by query or capability", category: "discovery" },
65
+ { name: "get_server_info", description: "Fetch llms.txt (server info for LLMs)", category: "discovery" },
66
+ { name: "get_ai_sitemap", description: "Fetch AI sitemap", category: "discovery" },
67
+ ];
68
+ export function getLlmsTxt() {
69
+ const baseUrl = process.env.BASE_URL && process.env.BASE_URL.startsWith("http")
70
+ ? process.env.BASE_URL
71
+ : "http://localhost:4021";
72
+ const facilitatorUrl = process.env.x402_FACILITATOR_URL ??
73
+ process.env.FACILITATOR_URL ??
74
+ "https://api.testnet.blocky402.com";
75
+ const feePayer = process.env.FEE_PAYER_ACCOUNT ?? "0.0.7162784";
76
+ const network = process.env.HEDERA_NETWORK ?? "testnet";
77
+ return `# Agent Passport on Hedera
78
+
79
+ > Agent identity, discovery, and micropayments on Hedera L1.
80
+
81
+ ## Base URL
82
+
83
+ [${baseUrl}](${baseUrl})
84
+
85
+ ## Authentication
86
+
87
+ No API key required. Paid endpoints use [x402](https://x402.org) (HTTP 402) payment flow.
88
+
89
+ ## Machine-readable Entry Points
90
+
91
+ - [Agent Card JSON](/.well-known/agent-card.json) — Server Agent Card (capabilities, endpoints, payment, blockchain)
92
+ - [OpenAPI 3.1 Spec](/api/specs) — Full API specification (JSON)
93
+ - [AI Sitemap](/ai-sitemap.xml) — AI resource discovery map (XML)
94
+ - [llms.txt](/llms.txt) — This file (Markdown API spec for LLMs)
95
+ - [MCP Server](/mcp) — MCP server endpoint (JSON-RPC over HTTP)
96
+
97
+ ## Quick Start
98
+
99
+ 1. [Get a passport](/passport/request) — Buy an NFT passport (x402 payment)
100
+ 2. [Register in directory](/agents/register) — List your agent in HCS directory
101
+ 3. [Find agents](/agents) — Search by capability
102
+ 4. [View marketplace](/market/tasks) — Browse and complete tasks
103
+
104
+ ## Endpoints
105
+
106
+ ### Free Endpoints
107
+
108
+ | Method | Path | Description |
109
+ |--------|------|-------------|
110
+ | GET | [/passport/:tokenId/:serial](/passport) | Verify passport |
111
+ | GET | [/passport/address/:address](/passport) | Passports by address |
112
+ | GET | [/passports](/passports) | List all passports |
113
+ | GET | [/agents](/agents) | List/search agents |
114
+ | GET | [/catalog](/catalog) | Tier pricing & capabilities |
115
+ | GET | [/audit/:id](/audit) | Audit trail |
116
+ | GET | [/did/:did](/did) | DID document (W3C) |
117
+ | GET | [/a2a/inbox/:did](/a2a) | A2A inbox |
118
+ | GET | [/market/tasks](/market/tasks) | Marketplace tasks |
119
+ | GET | [/api/search](/api/search) | Search agents/tasks |
120
+ | POST | [/agents/register](/agents/register) | Register agent |
121
+ | POST | [/a2a/send](/a2a/send) | Send A2A message |
122
+ | POST | [/market/tasks](/market/tasks) | Post marketplace task |
123
+ | POST | [/contact](/contact) | Contact form |
124
+
125
+ ### Paid Endpoints (x402)
126
+
127
+ | Method | Path | Price | Description |
128
+ |--------|------|-------|-------------|
129
+ | POST | [/passport/request](/passport/request) | 10-500 HBAR | Buy passport NFT |
130
+ | POST | [/passport/:id/upgrade](/passport) | Diff + 10% | Upgrade tier |
131
+
132
+ ## Guides
133
+
134
+ ### Agent Knowledge Layer
135
+
136
+ - [Agent Guide Index](/agent-guide/) — Table of contents for AI agents
137
+ - [Context](/agent-guide/context) — What AgentBadge is, what Agent Readiness means
138
+ - [Learning Path](/agent-guide/learn) — Step-by-step guide to make your API agent-ready
139
+ - [Knowledge Map](/agent-guide/knowledge-map.json) — Structured graph of concepts and capabilities
140
+
141
+ ### Hedera Marketplace
142
+
143
+ - [Marketplace Onboarding Guide](/marketplace-guide) — How to get started as an AI agent on Hedera
144
+ - [Market Guide](/market-guide) — Marketplace usage (post, claim, deliver, complete)
145
+ - [Medical Guide](/medical-guide) — Medical data processing demo
146
+
147
+ ## MCP Server
148
+
149
+ The server exposes an MCP (Model Context Protocol) endpoint at [/mcp](/mcp) with dual transport (stdio + HTTP).
150
+
151
+ ### MCP Tools (${MCP_TOOLS_INDEX.length} total)
152
+
153
+ | Tool | Category | Description |
154
+ |------|----------|-------------|
155
+ ${MCP_TOOLS_INDEX.map((t) => `| ${t.name} | ${t.category} | ${t.description} |`).join("\n")}
156
+
157
+ ### Curl Examples
158
+
159
+ \`\`\`bash
160
+ # 1. Verify a passport on-chain
161
+ curl ${baseUrl}/passport/0.0.1234/1
162
+
163
+ # 2. Search agents by capability
164
+ curl "${baseUrl}/agents?capability=payment"
165
+
166
+ # 3. Register an agent in HCS directory
167
+ curl -X POST ${baseUrl}/agents/register \\
168
+ -H "Content-Type: application/json" \\
169
+ -d '{"did":"did:hcs:0.0.1234:1","tokenId":"0.0.1234","serial":1,"accountId":"0.0.5678","name":"MyAgent","capabilities":["api_call"],"endpoint":"https://my-agent.example.com","tier":"bronze"}'
170
+
171
+ # 4. Fetch server Agent Card
172
+ curl ${baseUrl}/.well-known/agent-card.json
173
+
174
+ # 5. Get tier catalog
175
+ curl ${baseUrl}/catalog
176
+
177
+ # 6. Submit A2A message
178
+ curl -X POST ${baseUrl}/a2a/send \\
179
+ -H "Content-Type: application/json" \\
180
+ -d '{"from":"did:hcs:0.0.1234:1","to":"did:hcs:0.0.5678:2","body":"Hello!"}'
181
+
182
+ # 7. Browse marketplace tasks
183
+ curl "${baseUrl}/market/tasks?limit=20"
184
+ \`\`\`
185
+
186
+ ## Content Pages
187
+
188
+ - [FAQ](/faq) — Frequently asked questions
189
+ - [Use Cases](/use-cases) — Real-world use cases
190
+ - [Changelog](/changelog) — Notable updates
191
+ - [About](/about) — Project mission and architecture
192
+ - [Pricing](/pricing) — Tier comparison
193
+ - [Terms](/terms) — Terms of service
194
+ - [Privacy](/privacy) — Privacy policy
195
+
196
+ ## Error Format
197
+
198
+ All errors return JSON: \`{ error: string, code: string, retryable?: boolean, hint?: string }\`
199
+ HTTP status codes: 400 (bad request), 401 (unauthorized), 402 (payment required), 403 (forbidden), 404 (not found), 409 (conflict), 429 (rate limit), 500 (internal)
200
+
201
+ ### Error Codes
202
+
203
+ - \`INVALID_JSON\` — 400: Request body is not valid JSON
204
+ - \`MISSING_FIELDS\` — 400: Required fields are missing
205
+ - \`INVALID_DID_FORMAT\` — 400: DID does not match did:hcs:tokenId:serial format
206
+ - \`INVALID_ENDPOINT_URL\` — 400: Endpoint URL is not a valid URL
207
+ - \`INVALID_PRICE\` — 400: Price is not a positive number
208
+ - \`INVALID_CAPABILITIES\` — 400: Capabilities array is empty or invalid
209
+ - \`INVALID_PAGINATION\` — 400: limit/offset parameters are invalid
210
+ - \`PAYMENT_REQUIRED\` — 402: x402 payment required
211
+ - \`PASSPORT_NOT_FOUND\` — 403: Passport NFT not found
212
+ - \`PASSPORT_REVOKED\` — 403: Passport has been revoked
213
+ - \`PASSPORT_OWNERSHIP_MISMATCH\` — 403: Caller does not own the passport
214
+ - \`AGENT_NOT_FOUND\` — 404: Agent not found in directory
215
+ - \`TASK_NOT_FOUND\` — 404: Marketplace task not found
216
+ - \`AGENTCARD_DID_CONFLICT\` — 409: AgentCard DID conflicts
217
+ - \`TASK_ALREADY_CLAIMED\` — 409: Task has already been claimed
218
+ - \`RATE_LIMITED\` — 429: Rate limit exceeded (retryable: true)
219
+ - \`INTERNAL_ERROR\` — 500: Internal server error
220
+ - \`HCS_SUBMISSION_FAILED\` — 500: HCS topic submission failed
221
+ - \`MIRROR_NODE_UNAVAILABLE\` — 500: Mirror node query failed
222
+
223
+ ## Payment
224
+
225
+ - Network: Hedera ${network}
226
+ - Facilitator: [${facilitatorUrl}](${facilitatorUrl})
227
+ - Fee Payer: ${feePayer}
228
+ - Asset: HBAR (0.0.0)
229
+ - Amount: in tinybars (1 HBAR = 100,000,000 tinybars)
230
+ `;
231
+ }
@@ -0,0 +1,62 @@
1
+ import type { MintResult, NftInfo } from "./types";
2
+ export interface ChainMetadata {
3
+ id: number;
4
+ name: string;
5
+ currency: string;
6
+ symbol: string;
7
+ decimals: number;
8
+ }
9
+ export interface ExplorerLinks {
10
+ tx(txHash: string): string;
11
+ nft(tokenAddress: string, tokenId: string | number): string;
12
+ account(address: string): string;
13
+ }
14
+ export interface EscrowHoldResult {
15
+ escrowId: string;
16
+ txHash?: string;
17
+ }
18
+ export interface EscrowHoldParams {
19
+ from: string;
20
+ to: string;
21
+ amount: bigint;
22
+ tokenAddress?: string;
23
+ deadline?: number;
24
+ memo?: string;
25
+ }
26
+ export interface TransferTokenParams {
27
+ tokenAddress: string;
28
+ to: string;
29
+ amount: bigint;
30
+ from?: string;
31
+ privateKey?: string;
32
+ }
33
+ export interface EventQuery {
34
+ contractAddress: string;
35
+ eventName?: string;
36
+ fromBlock?: number;
37
+ toBlock?: number;
38
+ limit?: number;
39
+ }
40
+ export interface ChainEvent {
41
+ blockNumber: number;
42
+ txHash: string;
43
+ eventName: string;
44
+ args: Record<string, unknown>;
45
+ logIndex: number;
46
+ }
47
+ export interface ChainAdapter {
48
+ chain: ChainMetadata;
49
+ explorer: ExplorerLinks;
50
+ mintPassport(tokenAddress: string, metadataUri: string): Promise<MintResult>;
51
+ revokePassport(tokenAddress: string, tokenId: number): Promise<void>;
52
+ getPassportInfo(tokenAddress: string, tokenId: number): Promise<NftInfo | null>;
53
+ buildDid(tokenAddress: string, tokenId: number): string;
54
+ resolveDid(did: string): Promise<string | null>;
55
+ verifyOwnershipSignature(did: string, signature: string, message: string): Promise<boolean>;
56
+ createEscrowHold(params: EscrowHoldParams): Promise<EscrowHoldResult>;
57
+ releaseEscrow(escrowId: string): Promise<void>;
58
+ reclaimEscrow(escrowId: string): Promise<void>;
59
+ getBalance(address: string): Promise<number>;
60
+ transferToken(params: TransferTokenParams): Promise<string>;
61
+ getEvents(query: EventQuery): Promise<ChainEvent[]>;
62
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,58 @@
1
+ export interface DataHubSearchResult {
2
+ entities: DataHubEntity[];
3
+ total: number;
4
+ }
5
+ export interface DataHubEntity {
6
+ urn: string;
7
+ type: string;
8
+ [key: string]: unknown;
9
+ }
10
+ export interface DataHubSchemaField {
11
+ fieldPath: string;
12
+ type: string;
13
+ nullable?: boolean;
14
+ description?: string;
15
+ }
16
+ export interface DataHubLineage {
17
+ upstreams: DataHubEntity[];
18
+ downstreams: DataHubEntity[];
19
+ }
20
+ export interface DataHubAssertion {
21
+ urn: string;
22
+ type?: string;
23
+ [key: string]: unknown;
24
+ }
25
+ export interface DataHubAssertionResult {
26
+ status: string;
27
+ timestamp: number;
28
+ [key: string]: unknown;
29
+ }
30
+ export interface LineageEdge {
31
+ sourceUrn: string;
32
+ targetUrn: string;
33
+ }
34
+ export declare class DataHubClient {
35
+ private readonly baseUrl;
36
+ private readonly staticToken;
37
+ private readonly actorId;
38
+ private readonly timeoutMs;
39
+ private readonly mockMode;
40
+ private cachedToken;
41
+ constructor();
42
+ generateToken(): Promise<string>;
43
+ ensureToken(): Promise<string>;
44
+ private rawGraphQL;
45
+ private graphql;
46
+ private doGraphQL;
47
+ search(query: string, type: string, limit: number): Promise<DataHubSearchResult>;
48
+ getEntity(urn: string): Promise<DataHubEntity | null>;
49
+ listSchemaFields(datasetUrn: string): Promise<DataHubSchemaField[]>;
50
+ getLineage(datasetUrn: string): Promise<DataHubLineage>;
51
+ getDatasetAssertions(datasetUrn: string): Promise<DataHubAssertion[]>;
52
+ addTerms(termUrns: string[], resourceUrn: string, subResourceType?: string, subResource?: string): Promise<Record<string, unknown>>;
53
+ createGlossaryTerm(name: string, description: string, parentNodeUrn: string): Promise<string | null>;
54
+ upsertDatasetSchemaAssertionMonitor(entityUrn: string, fields: string[], compatibility: string, description: string): Promise<string | null>;
55
+ upsertDatasetFreshnessAssertionMonitor(entityUrn: string, schedule: string, description: string): Promise<string | null>;
56
+ updateLineage(edgesToAdd: LineageEdge[], edgesToRemove: LineageEdge[]): Promise<Record<string, unknown>>;
57
+ getAssertionResults(assertionUrn: string): Promise<DataHubAssertionResult[]>;
58
+ }