maiat-sdk 0.1.0 → 0.3.0
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.
- package/README.md +48 -16
- package/dist/index.d.ts +78 -2
- package/dist/index.js +34 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -19,10 +19,14 @@ const maiat = new Maiat();
|
|
|
19
19
|
const trusted = await maiat.isTrusted("0x...");
|
|
20
20
|
|
|
21
21
|
// Token safety check
|
|
22
|
-
const safe = await maiat.isTokenSafe(
|
|
22
|
+
const safe = await maiat.isTokenSafe(
|
|
23
|
+
"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
|
|
24
|
+
);
|
|
23
25
|
|
|
24
26
|
// Full trust score
|
|
25
|
-
const score = await maiat.agentTrust(
|
|
27
|
+
const score = await maiat.agentTrust(
|
|
28
|
+
"0xE6ac05D2b50cd525F793024D75BB6f519a52Af5D",
|
|
29
|
+
);
|
|
26
30
|
console.log(score.trustScore, score.verdict); // 69, "caution"
|
|
27
31
|
|
|
28
32
|
// Trust-verified swap quote
|
|
@@ -40,25 +44,53 @@ console.log(swap.calldata); // ready-to-sign tx calldata
|
|
|
40
44
|
|
|
41
45
|
### `new Maiat(config?)`
|
|
42
46
|
|
|
43
|
-
| Option
|
|
44
|
-
|
|
45
|
-
| `baseUrl` | `https://maiat
|
|
46
|
-
| `apiKey`
|
|
47
|
-
| `timeout` | `15000`
|
|
47
|
+
| Option | Default | Description |
|
|
48
|
+
| --------- | ----------------------------------- | --------------------------------------- |
|
|
49
|
+
| `baseUrl` | `https://app.maiat.io` | API base URL |
|
|
50
|
+
| `apiKey` | — | Optional API key for higher rate limits |
|
|
51
|
+
| `timeout` | `15000` | Request timeout (ms) |
|
|
48
52
|
|
|
49
53
|
### Methods
|
|
50
54
|
|
|
51
|
-
| Method
|
|
52
|
-
|
|
53
|
-
| `agentTrust(address)`
|
|
54
|
-
| `tokenCheck(address)`
|
|
55
|
-
| `trustSwap(params)`
|
|
56
|
-
| `listAgents(limit?)`
|
|
57
|
-
| `isTrusted(address, threshold?)` | `boolean`
|
|
58
|
-
| `isTokenSafe(address)`
|
|
55
|
+
| Method | Returns | Description |
|
|
56
|
+
| -------------------------------- | ------------------- | ---------------------------------- |
|
|
57
|
+
| `agentTrust(address)` | `AgentTrustResult` | Full trust score + breakdown |
|
|
58
|
+
| `tokenCheck(address)` | `TokenCheckResult` | Token safety analysis |
|
|
59
|
+
| `trustSwap(params)` | `TrustSwapResult` | Swap quote with trust verification |
|
|
60
|
+
| `listAgents(limit?)` | `{ agents, total }` | Browse indexed agents |
|
|
61
|
+
| `isTrusted(address, threshold?)` | `boolean` | Quick trust check (default ≥60) |
|
|
62
|
+
| `isTokenSafe(address)` | `boolean` | Quick token safety check |
|
|
63
|
+
|
|
64
|
+
## Outcome Reporting (Training Data)
|
|
65
|
+
|
|
66
|
+
The most valuable data for improving trust accuracy:
|
|
67
|
+
|
|
68
|
+
```typescript
|
|
69
|
+
const maiat = new Maiat({ clientId: "my-trading-bot" });
|
|
70
|
+
|
|
71
|
+
// 1. Check trust
|
|
72
|
+
const score = await maiat.agentTrust("0xCounterparty");
|
|
73
|
+
|
|
74
|
+
// 2. Take action based on trust
|
|
75
|
+
if (score.trustScore >= 60) {
|
|
76
|
+
// ... execute swap ...
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// 3. Report what happened
|
|
80
|
+
await maiat.reportOutcome({
|
|
81
|
+
target: "0xCounterparty",
|
|
82
|
+
action: "swap",
|
|
83
|
+
result: "success", // or "failure", "scam"
|
|
84
|
+
txHash: "0x...", // on-chain proof
|
|
85
|
+
maiatVerdict: score.verdict,
|
|
86
|
+
maiatScore: score.trustScore,
|
|
87
|
+
});
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
This closes the feedback loop: check → act → report → oracle gets smarter.
|
|
59
91
|
|
|
60
92
|
## Links
|
|
61
93
|
|
|
62
|
-
- Protocol: [maiat
|
|
94
|
+
- Protocol: [app.maiat.io](https://app.maiat.io)
|
|
63
95
|
- GitHub: [JhiNResH/maiat-protocol](https://github.com/JhiNResH/maiat-protocol)
|
|
64
96
|
- ACP: [Agent #3723 on Virtuals](https://app.virtuals.io/acp)
|
package/dist/index.d.ts
CHANGED
|
@@ -3,16 +3,19 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Usage:
|
|
5
5
|
* import { Maiat } from "maiat-sdk";
|
|
6
|
-
* const maiat = new Maiat();
|
|
6
|
+
* const maiat = new Maiat({ clientId: "my-agent" });
|
|
7
7
|
* const score = await maiat.agentTrust("0x...");
|
|
8
8
|
* const token = await maiat.tokenCheck("0x...");
|
|
9
9
|
* const swap = await maiat.trustSwap({ ... });
|
|
10
|
+
* await maiat.reportOutcome({ jobId: "...", outcome: "success" });
|
|
10
11
|
*/
|
|
11
12
|
export interface MaiatConfig {
|
|
12
|
-
/** Base URL for Maiat Protocol API. Default: https://maiat
|
|
13
|
+
/** Base URL for Maiat Protocol API. Default: https://app.maiat.io */
|
|
13
14
|
baseUrl?: string;
|
|
14
15
|
/** Optional API key for higher rate limits */
|
|
15
16
|
apiKey?: string;
|
|
17
|
+
/** Client identifier — tracks which agent/app is making requests (training data) */
|
|
18
|
+
clientId?: string;
|
|
16
19
|
/** Request timeout in ms. Default: 15000 */
|
|
17
20
|
timeout?: number;
|
|
18
21
|
}
|
|
@@ -29,6 +32,17 @@ export interface AgentTrustResult {
|
|
|
29
32
|
};
|
|
30
33
|
verdict: "proceed" | "caution" | "avoid";
|
|
31
34
|
lastUpdated: string;
|
|
35
|
+
feedback?: {
|
|
36
|
+
queryId: string;
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
export interface DeepAnalysisResult {
|
|
40
|
+
address: string;
|
|
41
|
+
trustScore: number;
|
|
42
|
+
verdict: "proceed" | "caution" | "avoid";
|
|
43
|
+
deepAnalysis: Record<string, unknown>;
|
|
44
|
+
signals: Record<string, unknown>;
|
|
45
|
+
lastUpdated: string;
|
|
32
46
|
}
|
|
33
47
|
export interface TokenCheckResult {
|
|
34
48
|
address: string;
|
|
@@ -39,6 +53,14 @@ export interface TokenCheckResult {
|
|
|
39
53
|
riskSummary: string;
|
|
40
54
|
dataSource: string;
|
|
41
55
|
}
|
|
56
|
+
export interface ForensicsResult {
|
|
57
|
+
address: string;
|
|
58
|
+
chain: string;
|
|
59
|
+
forensics: Record<string, unknown>;
|
|
60
|
+
riskFlags: string[];
|
|
61
|
+
verdict: "proceed" | "caution" | "avoid";
|
|
62
|
+
lastUpdated: string;
|
|
63
|
+
}
|
|
42
64
|
export interface TrustSwapParams {
|
|
43
65
|
swapper: string;
|
|
44
66
|
tokenIn: string;
|
|
@@ -64,16 +86,59 @@ export interface TrustSwapResult {
|
|
|
64
86
|
};
|
|
65
87
|
timestamp: string;
|
|
66
88
|
}
|
|
89
|
+
export interface OutcomeReport {
|
|
90
|
+
/** The agent or token address that was checked */
|
|
91
|
+
target: string;
|
|
92
|
+
/** What action was taken after checking trust */
|
|
93
|
+
action: "swap" | "delegate" | "hire" | "skip" | "block" | "other";
|
|
94
|
+
/** The outcome of that action */
|
|
95
|
+
result: "success" | "failure" | "scam" | "partial" | "pending";
|
|
96
|
+
/** On-chain tx hash as proof (optional) */
|
|
97
|
+
txHash?: string;
|
|
98
|
+
/** What Maiat verdict was at the time */
|
|
99
|
+
maiatVerdict?: "proceed" | "caution" | "avoid";
|
|
100
|
+
/** Trust score at the time of check */
|
|
101
|
+
maiatScore?: number;
|
|
102
|
+
/** Free-form context */
|
|
103
|
+
notes?: string;
|
|
104
|
+
}
|
|
105
|
+
export interface OutcomeResponse {
|
|
106
|
+
logged: boolean;
|
|
107
|
+
id?: string;
|
|
108
|
+
}
|
|
109
|
+
export interface OutcomeParams {
|
|
110
|
+
jobId: string;
|
|
111
|
+
outcome: "success" | "failure" | "partial" | "expired";
|
|
112
|
+
reporter?: string;
|
|
113
|
+
note?: string;
|
|
114
|
+
}
|
|
115
|
+
export interface OutcomeResult {
|
|
116
|
+
success: boolean;
|
|
117
|
+
id?: string;
|
|
118
|
+
message?: string;
|
|
119
|
+
}
|
|
120
|
+
export interface ScarabResult {
|
|
121
|
+
address: string;
|
|
122
|
+
balance: string;
|
|
123
|
+
balanceFormatted: number;
|
|
124
|
+
tier: string;
|
|
125
|
+
lastUpdated: string;
|
|
126
|
+
}
|
|
67
127
|
export declare class Maiat {
|
|
68
128
|
private baseUrl;
|
|
69
129
|
private apiKey?;
|
|
130
|
+
private clientId?;
|
|
70
131
|
private timeout;
|
|
71
132
|
constructor(config?: MaiatConfig);
|
|
72
133
|
private request;
|
|
73
134
|
/** Get trust score for an ACP agent by wallet address */
|
|
74
135
|
agentTrust(address: string): Promise<AgentTrustResult>;
|
|
136
|
+
/** Get deep analysis for an ACP agent by wallet address */
|
|
137
|
+
deep(address: string): Promise<DeepAnalysisResult>;
|
|
75
138
|
/** Check if a token is safe (honeypot, rug, liquidity) */
|
|
76
139
|
tokenCheck(address: string): Promise<TokenCheckResult>;
|
|
140
|
+
/** Get forensics data for a token address */
|
|
141
|
+
forensics(address: string, chain?: string): Promise<ForensicsResult>;
|
|
77
142
|
/** Get a trust-verified swap quote with calldata */
|
|
78
143
|
trustSwap(params: TrustSwapParams): Promise<TrustSwapResult>;
|
|
79
144
|
/** List indexed agents with trust scores */
|
|
@@ -81,6 +146,17 @@ export declare class Maiat {
|
|
|
81
146
|
agents: AgentTrustResult[];
|
|
82
147
|
total: number;
|
|
83
148
|
}>;
|
|
149
|
+
/** Get SCARAB token balance for an address */
|
|
150
|
+
scarab(address: string): Promise<ScarabResult>;
|
|
151
|
+
/**
|
|
152
|
+
* Report the outcome of a job (new API).
|
|
153
|
+
*
|
|
154
|
+
* Example flow:
|
|
155
|
+
* 1. maiat.agentTrust("0x...") → proceed
|
|
156
|
+
* 2. You execute the job
|
|
157
|
+
* 3. maiat.reportOutcome({ jobId: "...", outcome: "success" })
|
|
158
|
+
*/
|
|
159
|
+
reportOutcome(params: OutcomeParams): Promise<OutcomeResult>;
|
|
84
160
|
/** Quick check: is this agent trustworthy? Returns true if score >= threshold */
|
|
85
161
|
isTrusted(address: string, threshold?: number): Promise<boolean>;
|
|
86
162
|
/** Quick check: is this token safe to swap? */
|
package/dist/index.js
CHANGED
|
@@ -3,25 +3,29 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Usage:
|
|
5
5
|
* import { Maiat } from "maiat-sdk";
|
|
6
|
-
* const maiat = new Maiat();
|
|
6
|
+
* const maiat = new Maiat({ clientId: "my-agent" });
|
|
7
7
|
* const score = await maiat.agentTrust("0x...");
|
|
8
8
|
* const token = await maiat.tokenCheck("0x...");
|
|
9
9
|
* const swap = await maiat.trustSwap({ ... });
|
|
10
|
+
* await maiat.reportOutcome({ jobId: "...", outcome: "success" });
|
|
10
11
|
*/
|
|
11
12
|
// ─── Client ───────────────────────────────────────────────────────────────────
|
|
12
13
|
export class Maiat {
|
|
13
14
|
baseUrl;
|
|
14
15
|
apiKey;
|
|
16
|
+
clientId;
|
|
15
17
|
timeout;
|
|
16
18
|
constructor(config = {}) {
|
|
17
|
-
this.baseUrl = (config.baseUrl ?? "https://maiat
|
|
19
|
+
this.baseUrl = (config.baseUrl ?? "https://app.maiat.io").replace(/\/$/, "");
|
|
18
20
|
this.apiKey = config.apiKey;
|
|
21
|
+
this.clientId = config.clientId;
|
|
19
22
|
this.timeout = config.timeout ?? 15_000;
|
|
20
23
|
}
|
|
21
24
|
async request(path, options) {
|
|
22
25
|
const headers = {
|
|
23
26
|
"Content-Type": "application/json",
|
|
24
27
|
...(this.apiKey ? { "X-Maiat-Key": this.apiKey } : {}),
|
|
28
|
+
...(this.clientId ? { "X-Maiat-Client": this.clientId } : {}),
|
|
25
29
|
};
|
|
26
30
|
const res = await fetch(`${this.baseUrl}${path}`, {
|
|
27
31
|
...options,
|
|
@@ -39,10 +43,19 @@ export class Maiat {
|
|
|
39
43
|
async agentTrust(address) {
|
|
40
44
|
return this.request(`/api/v1/agent/${address}`);
|
|
41
45
|
}
|
|
46
|
+
/** Get deep analysis for an ACP agent by wallet address */
|
|
47
|
+
async deep(address) {
|
|
48
|
+
return this.request(`/api/v1/agent/${address}/deep`);
|
|
49
|
+
}
|
|
42
50
|
/** Check if a token is safe (honeypot, rug, liquidity) */
|
|
43
51
|
async tokenCheck(address) {
|
|
44
52
|
return this.request(`/api/v1/token/${address}`);
|
|
45
53
|
}
|
|
54
|
+
/** Get forensics data for a token address */
|
|
55
|
+
async forensics(address, chain) {
|
|
56
|
+
const query = chain ? `?chain=${chain}` : "";
|
|
57
|
+
return this.request(`/api/v1/token/${address}/forensics${query}`);
|
|
58
|
+
}
|
|
46
59
|
/** Get a trust-verified swap quote with calldata */
|
|
47
60
|
async trustSwap(params) {
|
|
48
61
|
return this.request("/api/v1/swap/quote", {
|
|
@@ -54,6 +67,25 @@ export class Maiat {
|
|
|
54
67
|
async listAgents(limit = 50) {
|
|
55
68
|
return this.request(`/api/v1/agents?limit=${limit}`);
|
|
56
69
|
}
|
|
70
|
+
/** Get SCARAB token balance for an address */
|
|
71
|
+
async scarab(address) {
|
|
72
|
+
return this.request(`/api/v1/scarab?address=${address}`);
|
|
73
|
+
}
|
|
74
|
+
// ─── Outcome Reporting ────────────────────────────────────────────────────
|
|
75
|
+
/**
|
|
76
|
+
* Report the outcome of a job (new API).
|
|
77
|
+
*
|
|
78
|
+
* Example flow:
|
|
79
|
+
* 1. maiat.agentTrust("0x...") → proceed
|
|
80
|
+
* 2. You execute the job
|
|
81
|
+
* 3. maiat.reportOutcome({ jobId: "...", outcome: "success" })
|
|
82
|
+
*/
|
|
83
|
+
async reportOutcome(params) {
|
|
84
|
+
return this.request("/api/v1/outcome", {
|
|
85
|
+
method: "POST",
|
|
86
|
+
body: JSON.stringify(params),
|
|
87
|
+
});
|
|
88
|
+
}
|
|
57
89
|
// ─── Convenience ──────────────────────────────────────────────────────────
|
|
58
90
|
/** Quick check: is this agent trustworthy? Returns true if score >= threshold */
|
|
59
91
|
async isTrusted(address, threshold = 60) {
|