@realmint/sdk 0.1.0 → 0.2.1

package/README.md

@@ -98,6 +98,33 @@ await fundWithX402(
 // USDC is bridged to the user's Injective smart account, ready for buy().
 ```
 
+## Keyless agent auth
+
+An autonomous agent holding only its own EVM key can authenticate without an API
+key: `agentLogin` exchanges an EOA signature for a bearer and returns a ready
+client.
+
+```ts
+import { agentLogin, fundWithX402, signerFromViemAccount } from "@realmint/sdk";
+import { privateKeyToAccount } from "viem/accounts";
+
+const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY!);
+const { client } = await agentLogin({
+  ownerEoa: account.address,
+  signMessage: (m) => account.signMessage({ message: m }),
+});
+
+await fundWithX402(client, { owner_eoa: account.address, amount_usdc: 5, asset_id: "tslax" }, payX402);
+await client.buy(
+  { asset_id: "tslax", source_token: "USDC", amount_in: 5, agent_wallet: account.address },
+  signerFromViemAccount(account),
+);
+```
+
+The bearer only authorizes quoting/creating intents for the EOA's own smart
+accounts; moving funds still requires the EOA's UserOp signature. See the
+[reference agent](https://github.com/realmint-io/realmint-x402-agent).
+
 ## Signing model
 
 `buy()` signs an **ERC-4337 UserOp v0.7** digest as an EIP-191 `personal_sign`

package/dist/agent.d.ts

@@ -0,0 +1,37 @@
+import { RealmintClient } from "./client.js";
+/**
+ * Signs an arbitrary text message as an EIP-191 `personal_sign`, returning the
+ * 0x signature. Build one from a viem account:
+ *   (m) => account.signMessage({ message: m })
+ * or an EIP-1193 provider:
+ *   (m) => provider.request({ method: "personal_sign", params: [m, address] })
+ */
+export type SignMessage = (message: string) => Promise<string>;
+export interface AgentLoginOptions {
+    /** The agent's EVM EOA — the identity it authenticates as. */
+    ownerEoa: string;
+    /** EIP-191 personal_sign over the challenge text. */
+    signMessage: SignMessage;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+export interface AgentSession {
+    /** A `RealmintClient` pre-configured with the minted bearer. */
+    client: RealmintClient;
+    accessToken: string;
+    ownerEoa: string;
+    /** Seconds until the bearer expires. */
+    expiresIn: number;
+}
+/**
+ * Keyless agent login: exchange an EOA signature for a bearer token — no API
+ * key. Requests a challenge, signs it, and returns a ready `RealmintClient`.
+ *
+ *   const { client } = await agentLogin({
+ *     ownerEoa: account.address,
+ *     signMessage: (m) => account.signMessage({ message: m }),
+ *   });
+ *   await client.buy({ asset_id: "tslax", source_token: "USDC", amount_in: 5,
+ *                      agent_wallet: account.address }, sign);
+ */
+export declare function agentLogin(opts: AgentLoginOptions): Promise<AgentSession>;

package/dist/agent.js

@@ -0,0 +1,64 @@
+import { RealmintClient } from "./client.js";
+const DEFAULT_BASE_URL = "https://api.realmint.io";
+/**
+ * Keyless agent login: exchange an EOA signature for a bearer token — no API
+ * key. Requests a challenge, signs it, and returns a ready `RealmintClient`.
+ *
+ *   const { client } = await agentLogin({
+ *     ownerEoa: account.address,
+ *     signMessage: (m) => account.signMessage({ message: m }),
+ *   });
+ *   await client.buy({ asset_id: "tslax", source_token: "USDC", amount_in: 5,
+ *                      agent_wallet: account.address }, sign);
+ */
+export async function agentLogin(opts) {
+    const base = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const f = opts.fetch ?? globalThis.fetch;
+    if (!f)
+        throw new Error("No fetch available — pass `fetch` in options (Node < 18).");
+    const challenge = await postJson(f, `${base}/v1/agent/auth/challenge`, {
+        owner_eoa: opts.ownerEoa,
+    });
+    const message = challenge.message;
+    const challengeToken = challenge.challenge_token;
+    if (!message || !challengeToken) {
+        throw new Error(`Unexpected challenge response: ${JSON.stringify(challenge)}`);
+    }
+    const signature = await opts.signMessage(message);
+    const token = await postJson(f, `${base}/v1/agent/auth/token`, {
+        challenge_token: challengeToken,
+        signature,
+    });
+    const accessToken = token.access_token;
+    if (!accessToken) {
+        throw new Error(`Agent auth failed: ${JSON.stringify(token)}`);
+    }
+    return {
+        client: new RealmintClient({ baseUrl: base, bearer: accessToken, fetch: opts.fetch }),
+        accessToken,
+        ownerEoa: opts.ownerEoa,
+        expiresIn: Number(token.expires_in ?? 3600),
+    };
+}
+async function postJson(f, url, body) {
+    const res = await f(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        parsed = text;
+    }
+    if (!res.ok) {
+        const msg = parsed?.message ??
+            parsed?.error ??
+            `HTTP ${res.status}`;
+        throw new Error(`${url} → ${msg}`);
+    }
+    return (parsed ?? {});
+}

package/dist/client.d.ts

@@ -15,7 +15,7 @@ export interface WaitOptions {
  */
 export declare class RealmintClient {
     private readonly baseUrl;
-    private readonly apiKey;
+    private readonly authHeaders;
     private readonly fetchImpl;
     constructor(opts: RealmintClientOptions);
     private request;
@@ -56,6 +56,11 @@ export declare class RealmintClient {
     }>;
     /** Submit a signed UserOp directly to the bundler; returns the userOp hash. */
     submitUserOp(bundlerUrl: string, signedUserOp: Record<string, unknown>, entrypoint: string): Promise<Hex>;
+    /**
+     * Poll the bundler for a UserOp receipt until it's mined; returns the source
+     * transaction hash (what `execute` needs). Throws if the UserOp reverts.
+     */
+    waitForUserOp(bundlerUrl: string, userOpHash: Hex, opts?: WaitOptions): Promise<string>;
     private bundlerRpc;
     /** Poll the intent until it reaches a terminal state (or times out). */
     waitForSettlement(intentId: string, opts?: WaitOptions): Promise<RouteIntent>;

package/dist/client.js

@@ -17,11 +17,20 @@ export class RealmintError extends Error {
  */
 export class RealmintClient {
     baseUrl;
-    apiKey;
+    authHeaders;
     fetchImpl;
     constructor(opts) {
         this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-        this.apiKey = opts.apiKey;
+        // Bearer (keyless agent auth) takes precedence; fall back to an API key.
+        if (opts.bearer) {
+            this.authHeaders = { authorization: `Bearer ${opts.bearer}` };
+        }
+        else if (opts.apiKey) {
+            this.authHeaders = { "x-api-key": opts.apiKey };
+        }
+        else {
+            throw new Error("Provide either `apiKey` or `bearer` in RealmintClient options.");
+        }
         this.fetchImpl = opts.fetch ?? globalThis.fetch;
         if (!this.fetchImpl) {
             throw new Error("No fetch available — pass `fetch` in options (Node < 18).");
@@ -32,7 +41,7 @@ export class RealmintClient {
         const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
             method,
             headers: {
-                "x-api-key": this.apiKey,
+                ...this.authHeaders,
                 ...(body !== undefined ? { "content-type": "application/json" } : {}),
             },
             body: body !== undefined ? JSON.stringify(body) : undefined,
@@ -124,6 +133,28 @@ export class RealmintClient {
         ]);
         return result;
     }
+    /**
+     * Poll the bundler for a UserOp receipt until it's mined; returns the source
+     * transaction hash (what `execute` needs). Throws if the UserOp reverts.
+     */
+    async waitForUserOp(bundlerUrl, userOpHash, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 120_000;
+        const pollMs = opts.pollMs ?? 2_000;
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const receipt = (await this.bundlerRpc(bundlerUrl, "eth_getUserOperationReceipt", [
+                userOpHash,
+            ]));
+            if (receipt) {
+                if (receipt.success === false) {
+                    throw new RealmintError("Source UserOp reverted on-chain", 200, receipt);
+                }
+                return receipt.receipt?.transactionHash ?? userOpHash;
+            }
+            await sleep(pollMs);
+        }
+        throw new RealmintError(`Timed out waiting for UserOp ${userOpHash} to be mined`, 408, null);
+    }
     async bundlerRpc(bundlerUrl, method, params) {
         const res = await this.fetchImpl(bundlerUrl, {
             method: "POST",
@@ -175,9 +206,13 @@ export class RealmintClient {
         const signedUserOp = { ...prep.source_user_op, signature };
         const entrypoint = prep.entrypoint_address ?? account.entrypoint_address;
         const userOpHash = await this.submitUserOp(account.bundler_url, signedUserOp, entrypoint);
+        // `execute` requires the source tx to be MINED (else 400 source_tx_not_mined);
+        // a UserOp hash is not a tx hash. Wait for inclusion, then execute with the
+        // real source tx hash before the quote expires.
+        const sourceTxHash = await this.waitForUserOp(account.bundler_url, userOpHash, opts);
         await this.executeIntent(created.intent_id, {
             agent_wallet: params.agent_wallet,
-            source_tx_hash: userOpHash,
+            source_tx_hash: sourceTxHash,
         });
         return this.waitForSettlement(created.intent_id, opts);
     }

package/dist/index.d.ts

@@ -3,5 +3,7 @@ export type { WaitOptions } from "./client.js";
 export { signerFromViemAccount, signerFromEip1193 } from "./signing.js";
 export { fundWithX402 } from "./x402.js";
 export type { X402PaymentSigner } from "./x402.js";
+export { agentLogin } from "./agent.js";
+export type { AgentLoginOptions, AgentSession, SignMessage } from "./agent.js";
 export type { AccountStatus, CreateIntentParams, CreateIntentResponse, ExecuteResponse, GetIntentResponse, Hex, PrepareResponse, PrepareSolanaSellResponse, QuoteBreakdown, RealmintClientOptions, RouteIntent, SignSolanaWire, SignUserOpHash, TradeAction, UnsignedUserOp, } from "./types.js";
 export { TERMINAL_STATES } from "./types.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { RealmintClient, RealmintError } from "./client.js";
 export { signerFromViemAccount, signerFromEip1193 } from "./signing.js";
 export { fundWithX402 } from "./x402.js";
+export { agentLogin } from "./agent.js";
 export { TERMINAL_STATES } from "./types.js";

package/dist/types.d.ts

@@ -2,8 +2,14 @@ export type Hex = `0x${string}`;
 export interface RealmintClientOptions {
     /** API base URL. Defaults to https://api.realmint.io */
     baseUrl?: string;
-    /** Partner API key, sent as `x-api-key`. */
-    apiKey: string;
+    /** Partner API key, sent as `x-api-key`. Provide this or `bearer`. */
+    apiKey?: string;
+    /**
+     * OAuth bearer token, sent as `Authorization: Bearer`. Mint one keyless from
+     * an EOA signature with `agentLogin` — no API key needed. Takes precedence
+     * over `apiKey` when both are set.
+     */
+    bearer?: string;
     /** Override the global fetch (e.g. a proxy-aware fetch). */
     fetch?: typeof fetch;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realmint/sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "TypeScript SDK for the Realmint API — list, buy, and sell tokenized RWAs (non-custodial; the partner's signer signs).",
   "license": "MIT",
   "type": "module",