@realmint/sdk 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# @realmint/sdk
+
+TypeScript SDK for the [Realmint](https://realmint.io) API — **list, buy, and
+sell** tokenized real-world assets. Non-custodial: you inject the signer, the
+SDK never holds keys. Gas is sponsored in USDC (no native gas needed), and
+funding is over [x402](https://x402.org).
+
+```bash
+npm install @realmint/sdk
+```
+
+You bring your own EVM signer (viem account or an EIP-1193 provider). For Solana
+sells you also bring a Solana signer. Node 18+ (native `fetch`).
+
+## Quick start
+
+```ts
+import { RealmintClient, signerFromViemAccount } from "@realmint/sdk";
+import { privateKeyToAccount } from "viem/accounts";
+
+const client = new RealmintClient({ apiKey: process.env.REALMINT_API_KEY! });
+
+// The user's EVM account (the partner manages this key, not Realmint).
+const account = privateKeyToAccount(userPrivateKey);
+const sign = signerFromViemAccount(account);
+```
+
+## List
+
+```ts
+const assets = await client.listAssets({ roots: true });
+const paxg = await client.getAsset("paxg");
+const score = await client.getScore("paxg");
+const venues = await client.getRouteSupport("paxg");
+const holdings = await client.getPortfolio(account.address);
+```
+
+## Buy
+
+`buy()` runs the whole lifecycle: create → prepare → **sign the UserOp** →
+submit to the bundler → execute → poll to completion. The user's smart account
+must already hold USDC (fund it with `fundWithX402` first).
+
+```ts
+const intent = await client.buy(
+  {
+    asset_id: "paxg",
+    source_token: "USDC",
+    amount_in: 100,            // 100 USDC
+    agent_wallet: account.address,
+  },
+  sign,
+);
+console.log(intent.status); // "completed"
+```
+
+## Sell
+
+EVM-deployed assets sell with **zero signatures** (the protocol executes the
+swap via a session key):
+
+```ts
+const sold = await client.sellEvm({
+  asset_id: "paxg",
+  source_token: "USDC",
+  amount_in: 0.05,            // asset quantity to sell
+  agent_wallet: account.address,
+});
+```
+
+Solana-deployed assets take **one** Solana signature on the prepared wire:
+
+```ts
+import { SignSolanaWire } from "@realmint/sdk";
+
+const signWire: SignSolanaWire = async (wireBase64) => {
+  // co-sign the base64 V0 transaction with the user's Solana key, return base64
+};
+const sold = await client.sellSolana(
+  { asset_id: "tslax", source_token: "USDC", amount_in: 1, agent_wallet: account.address },
+  signWire,
+);
+```
+
+## Fund with x402
+
+```ts
+import { fundWithX402 } from "@realmint/sdk";
+
+await fundWithX402(
+  client,
+  { owner_eoa: account.address, amount_usdc: 100 },
+  async (paymentRequirements) => {
+    // settle the requirements with your x402 client (e.g. the Coinbase x402 SDK
+    // with a viem account on Base) and return the encoded X-PAYMENT header value
+  },
+);
+// USDC is bridged to the user's Injective smart account, ready for buy().
+```
+
+## Signing model
+
+`buy()` signs an **ERC-4337 UserOp v0.7** digest as an EIP-191 `personal_sign`
+over the 32-byte hash — that's what `signerFromViemAccount` /
+`signerFromEip1193` produce. Don't use an EIP-712 typed sign or a raw ECDSA
+sign; the smart account validates the personal_sign form.
+
+Lower-level methods (`accountStatus`, `createIntent`, `prepareIntent`,
+`executeIntent`, `getIntent`, `reconcileIntent`, `waitForSettlement`,
+`submitUserOp`) are exposed if you need to drive the lifecycle yourself.
+
+See the full API reference at https://api.realmint.io/docs.

package/dist/client.d.ts

@@ -0,0 +1,79 @@
+import type { AccountStatus, CreateIntentParams, CreateIntentResponse, ExecuteResponse, GetIntentResponse, Hex, PrepareResponse, PrepareSolanaSellResponse, RealmintClientOptions, RouteIntent, SignSolanaWire, SignUserOpHash } from "./types.js";
+export declare class RealmintError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export interface WaitOptions {
+    timeoutMs?: number;
+    pollMs?: number;
+}
+/**
+ * Client for the Realmint trading API. Non-custodial: signing is done by a
+ * caller-supplied signer (see `SignUserOpHash` / `signing.ts`); the SDK never
+ * holds keys.
+ */
+export declare class RealmintClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor(opts: RealmintClientOptions);
+    private request;
+    listAssets(params?: {
+        roots?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown[]>;
+    getAsset(assetId: string): Promise<unknown>;
+    getScore(assetId: string): Promise<unknown>;
+    getRouteSupport(assetId: string): Promise<unknown>;
+    getPortfolio(wallet: string): Promise<unknown>;
+    accountStatus(wallet: string): Promise<AccountStatus>;
+    createIntent(params: CreateIntentParams): Promise<CreateIntentResponse>;
+    prepareIntent(intentId: string): Promise<PrepareResponse>;
+    executeIntent(intentId: string, body: {
+        agent_wallet: string;
+        source_tx_hash?: string;
+        min_amount_out?: number;
+    }): Promise<ExecuteResponse>;
+    reconcileIntent(intentId: string): Promise<unknown>;
+    getIntent(intentId: string): Promise<GetIntentResponse>;
+    prepareSolanaSell(intentId: string): Promise<PrepareSolanaSellResponse>;
+    submitSolanaSell(intentId: string, signedWireBase64: string): Promise<unknown>;
+    /**
+     * Raw x402 funding call. Without `xPaymentHeader` you get a 402 whose body
+     * carries the payment requirements; settle them with an x402 client and call
+     * again with the encoded `X-PAYMENT` header. Returns the HTTP status + body
+     * so the caller can branch on 402. Public endpoint — no api-key needed.
+     */
+    x402Buy(params: {
+        owner_eoa: string;
+        amount_usdc: number;
+        asset_id?: string;
+    }, xPaymentHeader?: string): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+    /** Submit a signed UserOp directly to the bundler; returns the userOp hash. */
+    submitUserOp(bundlerUrl: string, signedUserOp: Record<string, unknown>, entrypoint: string): Promise<Hex>;
+    private bundlerRpc;
+    /** Poll the intent until it reaches a terminal state (or times out). */
+    waitForSettlement(intentId: string, opts?: WaitOptions): Promise<RouteIntent>;
+    /**
+     * Buy an asset end to end: create → prepare → sign (UserOp v0.7) → submit to
+     * the bundler → execute → poll to completion. The user's funds must already
+     * be in their smart account (fund via x402 first). Returns the settled intent.
+     */
+    buy(params: Omit<CreateIntentParams, "action">, sign: SignUserOpHash, opts?: WaitOptions): Promise<RouteIntent>;
+    /**
+     * Sell an EVM-deployed asset: 0-signature. Creating the intent is the commit;
+     * the protocol executes the source swap via a session key. Returns the
+     * settled intent.
+     */
+    sellEvm(params: Omit<CreateIntentParams, "action">, opts?: WaitOptions): Promise<RouteIntent>;
+    /**
+     * Sell a Solana-deployed asset: create → prepare wire → user co-signs → submit
+     * → poll. One Solana signature; gas is relayer-sponsored.
+     */
+    sellSolana(params: Omit<CreateIntentParams, "action">, signWire: SignSolanaWire, opts?: WaitOptions): Promise<RouteIntent>;
+}

package/dist/client.js

@@ -0,0 +1,216 @@
+import { TERMINAL_STATES } from "./types.js";
+const DEFAULT_BASE_URL = "https://api.realmint.io";
+export class RealmintError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "RealmintError";
+    }
+}
+/**
+ * Client for the Realmint trading API. Non-custodial: signing is done by a
+ * caller-supplied signer (see `SignUserOpHash` / `signing.ts`); the SDK never
+ * holds keys.
+ */
+export class RealmintClient {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    constructor(opts) {
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.apiKey = opts.apiKey;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl) {
+            throw new Error("No fetch available — pass `fetch` in options (Node < 18).");
+        }
+    }
+    // ── HTTP ──────────────────────────────────────────────────────────────
+    async request(method, path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                "x-api-key": this.apiKey,
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        const parsed = text ? safeJson(text) : undefined;
+        if (!res.ok) {
+            const msg = parsed?.message ??
+                parsed?.error ??
+                `Realmint API ${res.status}`;
+            throw new RealmintError(msg, res.status, parsed ?? text);
+        }
+        return parsed;
+    }
+    // ── Read (list) ───────────────────────────────────────────────────────
+    listAssets(params) {
+        const q = new URLSearchParams();
+        if (params?.roots)
+            q.set("roots", "true");
+        if (params?.limit != null)
+            q.set("limit", String(params.limit));
+        if (params?.offset != null)
+            q.set("offset", String(params.offset));
+        const qs = q.toString();
+        return this.request("GET", `/v1/assets/summary${qs ? `?${qs}` : ""}`);
+    }
+    getAsset(assetId) {
+        return this.request("GET", `/v1/assets/${encodeURIComponent(assetId)}`);
+    }
+    getScore(assetId) {
+        return this.request("GET", `/v1/assets/${encodeURIComponent(assetId)}/score`);
+    }
+    getRouteSupport(assetId) {
+        return this.request("GET", `/v1/assets/${encodeURIComponent(assetId)}/route-support`);
+    }
+    getPortfolio(wallet) {
+        return this.request("GET", `/v1/portfolio/${encodeURIComponent(wallet)}`);
+    }
+    // ── Routing primitives ────────────────────────────────────────────────
+    accountStatus(wallet) {
+        return this.request("GET", `/v1/account/status?wallet=${encodeURIComponent(wallet)}`);
+    }
+    createIntent(params) {
+        return this.request("POST", "/v1/route/intent", params);
+    }
+    prepareIntent(intentId) {
+        return this.request("POST", `/v1/route/intent/${intentId}/prepare`);
+    }
+    executeIntent(intentId, body) {
+        return this.request("POST", `/v1/route/intent/${intentId}/execute`, body);
+    }
+    reconcileIntent(intentId) {
+        return this.request("POST", `/v1/route/intent/${intentId}/reconcile`);
+    }
+    getIntent(intentId) {
+        return this.request("GET", `/v1/route/intent/${intentId}`);
+    }
+    prepareSolanaSell(intentId) {
+        return this.request("POST", `/v1/route/intent/${intentId}/solana-sell/prepare`);
+    }
+    submitSolanaSell(intentId, signedWireBase64) {
+        return this.request("POST", `/v1/route/intent/${intentId}/solana-sell/submit`, { transaction: signedWireBase64 });
+    }
+    // ── x402 funding ──────────────────────────────────────────────────────
+    /**
+     * Raw x402 funding call. Without `xPaymentHeader` you get a 402 whose body
+     * carries the payment requirements; settle them with an x402 client and call
+     * again with the encoded `X-PAYMENT` header. Returns the HTTP status + body
+     * so the caller can branch on 402. Public endpoint — no api-key needed.
+     */
+    async x402Buy(params, xPaymentHeader) {
+        const res = await this.fetchImpl(`${this.baseUrl}/v1/route/x402-buy`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                ...(xPaymentHeader ? { "X-PAYMENT": xPaymentHeader } : {}),
+            },
+            body: JSON.stringify(params),
+        });
+        const text = await res.text();
+        return { status: res.status, body: text ? safeJson(text) : undefined };
+    }
+    // ── Bundler (ERC-4337) ────────────────────────────────────────────────
+    /** Submit a signed UserOp directly to the bundler; returns the userOp hash. */
+    async submitUserOp(bundlerUrl, signedUserOp, entrypoint) {
+        const result = await this.bundlerRpc(bundlerUrl, "eth_sendUserOperation", [
+            signedUserOp,
+            entrypoint,
+        ]);
+        return result;
+    }
+    async bundlerRpc(bundlerUrl, method, params) {
+        const res = await this.fetchImpl(bundlerUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+        });
+        const json = (await res.json().catch(() => null));
+        if (!res.ok || json?.error) {
+            throw new Error(`Bundler error: ${json?.error?.message ?? res.status}`);
+        }
+        return json?.result;
+    }
+    // ── Polling ───────────────────────────────────────────────────────────
+    /** Poll the intent until it reaches a terminal state (or times out). */
+    async waitForSettlement(intentId, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 180_000;
+        const pollMs = opts.pollMs ?? 3_000;
+        const deadline = Date.now() + timeoutMs;
+        let last;
+        while (Date.now() < deadline) {
+            // A reconcile nudge advances bridge/destination stages between polls.
+            await this.reconcileIntent(intentId).catch(() => undefined);
+            const { intent } = await this.getIntent(intentId);
+            last = intent;
+            if (TERMINAL_STATES.includes(intent.status)) {
+                if (intent.status !== "completed") {
+                    throw new RealmintError(`Intent ${intentId} ended in ${intent.status}${intent.last_error ? `: ${intent.last_error}` : ""}`, 200, intent);
+                }
+                return intent;
+            }
+            await sleep(pollMs);
+        }
+        throw new RealmintError(`Timed out waiting for intent ${intentId} (last status: ${last?.status ?? "unknown"})`, 408, last);
+    }
+    // ── High-level flows ──────────────────────────────────────────────────
+    /**
+     * Buy an asset end to end: create → prepare → sign (UserOp v0.7) → submit to
+     * the bundler → execute → poll to completion. The user's funds must already
+     * be in their smart account (fund via x402 first). Returns the settled intent.
+     */
+    async buy(params, sign, opts = {}) {
+        const account = await this.accountStatus(params.agent_wallet);
+        const created = await this.createIntent({ ...params, action: "buy" });
+        const prep = await this.prepareIntent(created.intent_id);
+        if (!prep.source_user_op || !prep.source_user_op_hash) {
+            throw new RealmintError("This route uses a non-UserOp lane the SDK doesn't sign yet (e.g. deBridge). Use the raw API.", 501, prep);
+        }
+        const signature = await sign(prep.source_user_op_hash);
+        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);
+        await this.executeIntent(created.intent_id, {
+            agent_wallet: params.agent_wallet,
+            source_tx_hash: userOpHash,
+        });
+        return this.waitForSettlement(created.intent_id, opts);
+    }
+    /**
+     * Sell an EVM-deployed asset: 0-signature. Creating the intent is the commit;
+     * the protocol executes the source swap via a session key. Returns the
+     * settled intent.
+     */
+    async sellEvm(params, opts = {}) {
+        const created = await this.createIntent({ ...params, action: "sell" });
+        await this.executeIntent(created.intent_id, { agent_wallet: params.agent_wallet }).catch(() => undefined);
+        return this.waitForSettlement(created.intent_id, opts);
+    }
+    /**
+     * Sell a Solana-deployed asset: create → prepare wire → user co-signs → submit
+     * → poll. One Solana signature; gas is relayer-sponsored.
+     */
+    async sellSolana(params, signWire, opts = {}) {
+        const created = await this.createIntent({ ...params, action: "sell" });
+        const prep = await this.prepareSolanaSell(created.intent_id);
+        const signed = await signWire(prep.unsigned_tx_wire_base64);
+        await this.submitSolanaSell(created.intent_id, signed);
+        return this.waitForSettlement(created.intent_id, opts);
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { RealmintClient, RealmintError } from "./client.js";
+export type { WaitOptions } from "./client.js";
+export { signerFromViemAccount, signerFromEip1193 } from "./signing.js";
+export { fundWithX402 } from "./x402.js";
+export type { X402PaymentSigner } from "./x402.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

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

package/dist/signing.d.ts

@@ -0,0 +1,29 @@
+import type { Hex, SignUserOpHash } from "./types.js";
+/** Structural shape of a viem `LocalAccount` — avoids a hard viem dependency. */
+interface ViemLikeAccount {
+    signMessage(args: {
+        message: {
+            raw: Hex;
+        };
+    }): Promise<string>;
+}
+/**
+ * Build a UserOp signer from a viem account. `signMessage({ message: { raw } })`
+ * is an EIP-191 personal_sign over the raw 32-byte hash — exactly what the
+ * smart account validates.
+ */
+export declare function signerFromViemAccount(account: ViemLikeAccount): SignUserOpHash;
+/** Structural shape of an EIP-1193 provider (window.ethereum / Privy). */
+interface Eip1193Provider {
+    request(args: {
+        method: string;
+        params: unknown[];
+    }): Promise<unknown>;
+}
+/**
+ * Build a UserOp signer from an EIP-1193 provider. Uses `personal_sign`, which
+ * the provider treats as an EIP-191 sign over the hash bytes — matching the
+ * Realmint web client.
+ */
+export declare function signerFromEip1193(provider: Eip1193Provider, address: string): SignUserOpHash;
+export {};

package/dist/signing.js

@@ -0,0 +1,19 @@
+/**
+ * Build a UserOp signer from a viem account. `signMessage({ message: { raw } })`
+ * is an EIP-191 personal_sign over the raw 32-byte hash — exactly what the
+ * smart account validates.
+ */
+export function signerFromViemAccount(account) {
+    return (hash) => account.signMessage({ message: { raw: hash } });
+}
+/**
+ * Build a UserOp signer from an EIP-1193 provider. Uses `personal_sign`, which
+ * the provider treats as an EIP-191 sign over the hash bytes — matching the
+ * Realmint web client.
+ */
+export function signerFromEip1193(provider, address) {
+    return async (hash) => (await provider.request({
+        method: "personal_sign",
+        params: [hash, address],
+    }));
+}

package/dist/types.d.ts

@@ -0,0 +1,112 @@
+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;
+    /** Override the global fetch (e.g. a proxy-aware fetch). */
+    fetch?: typeof fetch;
+}
+export interface AccountStatus {
+    wallet: string;
+    smart_account: string;
+    smart_account_deployed: boolean;
+    bundler_url: string;
+    entrypoint_address: string;
+    readiness_state: string;
+    one_click_source_tokens: string[];
+    degraded_reason: string | null;
+}
+export type TradeAction = "buy" | "sell";
+export interface CreateIntentParams {
+    asset_id: string;
+    action: TradeAction;
+    /** Funding token on the source chain — "USDC" for the standard rail. */
+    source_token: string;
+    /** Human units (e.g. 100.0 USDC for a buy; asset quantity for a sell). */
+    amount_in: number;
+    /** The user's EVM address. Realmint derives their smart account from it. */
+    agent_wallet: string;
+    destination_chain_id?: number;
+    destination_token?: string;
+    min_amount_out?: number;
+    slippage_bps?: number;
+    /** Return a quote without persisting an intent. */
+    quote_only?: boolean;
+}
+export interface QuoteBreakdown {
+    source_token: string;
+    net_amount_out: number;
+    total_cost_usd: number;
+    confidence: string;
+    expires_at: string;
+    [k: string]: unknown;
+}
+export interface CreateIntentResponse {
+    intent_id: string;
+    quote_id: string;
+    status: string;
+    quote: QuoteBreakdown;
+    expires_in_seconds: number;
+}
+/** ERC-4337 v0.7 UserOp as returned by /prepare; `signature` is empty. */
+export interface UnsignedUserOp {
+    sender: string;
+    nonce: string;
+    signature: string;
+    [k: string]: unknown;
+}
+export interface PrepareResponse {
+    intent_id: string;
+    /** Present for the CCTP / UserOp lanes — the SDK's buy path. */
+    source_user_op?: UnsignedUserOp;
+    /** EIP-712 UserOp digest the user signs (personal_sign / EIP-191). */
+    source_user_op_hash?: Hex;
+    entrypoint_address?: string;
+    smart_account_address?: string;
+    /** Present for non-UserOp lanes (e.g. deBridge) — not handled by the SDK yet. */
+    unsigned_tx?: Record<string, unknown>;
+    bridge_provider?: string;
+}
+export interface ExecuteResponse {
+    intent_id: string;
+    status: string;
+    source_tx_hash: string | null;
+    message: string;
+}
+export interface RouteIntent {
+    id: string;
+    asset_id: string;
+    action: string;
+    status: string;
+    agent_wallet: string;
+    source_tx_hash: string | null;
+    destination_tx_hash: string | null;
+    last_error: string | null;
+    [k: string]: unknown;
+}
+export interface GetIntentResponse {
+    intent: RouteIntent;
+    steps: unknown[];
+}
+export interface PrepareSolanaSellResponse {
+    intent_id: string;
+    /** Base64 V0 transaction wire, partially signed; the user co-signs it. */
+    unsigned_tx_wire_base64: string;
+    min_usdc_out: number | string;
+    expected_signer: string;
+}
+/** Terminal-ish states the SDK's waiters stop on. */
+export declare const TERMINAL_STATES: readonly ["completed", "terminal_failed", "expired", "cancelled"];
+/**
+ * Signs an ERC-4337 UserOp digest the way the smart account expects: an
+ * EIP-191 `personal_sign` over the 32-byte hash (NOT an EIP-712 typed sign and
+ * NOT a raw ECDSA sign). Return the 0x-prefixed signature.
+ *
+ * Build one with the helpers in `signing.ts`, or inline:
+ *   viem:    (hash) => account.signMessage({ message: { raw: hash } })
+ *   EIP-1193: (hash) => provider.request({ method: "personal_sign", params: [hash, address] })
+ */
+export type SignUserOpHash = (userOpHash: Hex) => Promise<string>;
+/** Signs a base64 Solana transaction wire, returning the co-signed wire. */
+export type SignSolanaWire = (unsignedWireBase64: string) => Promise<string>;

package/dist/types.js

@@ -0,0 +1,8 @@
+// Wire types — a partner-facing subset of the Realmint API responses.
+/** Terminal-ish states the SDK's waiters stop on. */
+export const TERMINAL_STATES = [
+    "completed",
+    "terminal_failed",
+    "expired",
+    "cancelled",
+];

package/dist/x402.d.ts

@@ -0,0 +1,19 @@
+import type { RealmintClient } from "./client.js";
+/**
+ * Given the 402 payment-requirements body, produce the encoded `X-PAYMENT`
+ * header value. Implement this with an x402 client (e.g. the Coinbase x402 SDK
+ * with a viem account on Base) — the SDK stays unopinionated about which one.
+ */
+export type X402PaymentSigner = (paymentRequirements: unknown) => Promise<string>;
+/**
+ * Fund a user's smart account in USDC over x402: request the challenge, have
+ * `paySigner` settle it, retry with the `X-PAYMENT` header. Realmint then
+ * bridges the USDC to the user's Injective smart account, ready for `buy()`.
+ *
+ * @returns the final settlement body from the API.
+ */
+export declare function fundWithX402(client: RealmintClient, params: {
+    owner_eoa: string;
+    amount_usdc: number;
+    asset_id?: string;
+}, paySigner: X402PaymentSigner): Promise<unknown>;

package/dist/x402.js

@@ -0,0 +1,21 @@
+/**
+ * Fund a user's smart account in USDC over x402: request the challenge, have
+ * `paySigner` settle it, retry with the `X-PAYMENT` header. Realmint then
+ * bridges the USDC to the user's Injective smart account, ready for `buy()`.
+ *
+ * @returns the final settlement body from the API.
+ */
+export async function fundWithX402(client, params, paySigner) {
+    const challenge = await client.x402Buy(params);
+    if (challenge.status !== 402) {
+        if (challenge.status >= 200 && challenge.status < 300)
+            return challenge.body;
+        throw new Error(`Expected a 402 funding challenge, got ${challenge.status}: ${JSON.stringify(challenge.body)}`);
+    }
+    const xPayment = await paySigner(challenge.body);
+    const settled = await client.x402Buy(params, xPayment);
+    if (settled.status < 200 || settled.status >= 300) {
+        throw new Error(`x402 settlement failed (${settled.status}): ${JSON.stringify(settled.body)}`);
+    }
+    return settled.body;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@realmint/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Realmint API — list, buy, and sell tokenized RWAs (non-custodial; the partner's signer signs).",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "realmint",
+    "rwa",
+    "defi",
+    "erc-4337",
+    "x402"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}