@keelcodes/sdk 2.3.2 → 2.4.0

package/dist/aa/index.d.ts

@@ -7,5 +7,6 @@ export * from './userop';
 export * from './kernel-account';
 export * from './keel-session';
 export * from './x402';
+export * from './x402-solana';
 export * from './x402-session';
 export * from './bundler';

package/dist/aa/index.js

@@ -26,5 +26,6 @@ __exportStar(require("./userop"), exports);
 __exportStar(require("./kernel-account"), exports);
 __exportStar(require("./keel-session"), exports);
 __exportStar(require("./x402"), exports);
+__exportStar(require("./x402-solana"), exports);
 __exportStar(require("./x402-session"), exports);
 __exportStar(require("./bundler"), exports);

package/dist/aa/x402-solana.d.ts

@@ -0,0 +1,99 @@
+import type { X402Accept, X402PaymentRequired, X402ResourceInfo } from './x402';
+/** CAIP-2 Solana network 前缀（如 `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`）。 */
+export declare const SOLANA_NETWORK_PREFIX = "solana:";
+/** Solana x402 签名域分隔标签。 */
+export declare const SOLANA_X402_DOMAIN = "x402-solana-v2";
+/** Solana 原生资产标签（与账本 `asset` 列一致，金额单位为 lamports）。 */
+export declare const SOLANA_X402_ASSET = "sol";
+export interface X402SolanaPaymentPayload {
+    x402Version: 2;
+    resource?: X402ResourceInfo;
+    accepted: X402Accept;
+    payload: {
+        method: string;
+        url: string;
+        /** 重放保护随机串（字符串即可；缺省由 txHash + 时间派生） */
+        salt: string;
+        /** 链上付款交易签名（base58） */
+        txHash: string;
+        /** 付款人公钥（base58） */
+        payer: string;
+    };
+    extensions?: Record<string, unknown>;
+    /** base58(ed25519 signature, 64B) */
+    signature: string;
+}
+/** 链上付款参数：向 `to` 转 `lamports`，原生 SOL。 */
+export interface X402SolanaPayment {
+    to: string;
+    lamports: bigint;
+    asset: typeof SOLANA_X402_ASSET;
+}
+/**
+ * Solana 会话签名器：只需公钥 + 对原始消息签名。
+ * 私钥始终留在客户端（session key / 智能账户），SDK 不接触。
+ */
+export interface X402SolanaSigner {
+    /** base58 公钥（= payload.payer） */
+    publicKey: string;
+    /** 返回 64B 签名：Uint8Array 或 base58 字符串 */
+    signMessage(message: Uint8Array): Promise<Uint8Array | string>;
+}
+export interface PayX402WithSolanaParams {
+    challenge: X402PaymentRequired;
+    /** 不传则自动选第一个 Solana accept */
+    accept?: X402Accept;
+    /** 发起链上转账并返回交易签名（base58） */
+    sendPayment: (payment: X402SolanaPayment) => Promise<{
+        signature: string;
+        payer?: string;
+    }>;
+    signer: X402SolanaSigner;
+    /** 等交易确认（建议传入，避免服务端校验时还查不到） */
+    waitForConfirmation?: (signature: string) => Promise<unknown>;
+    method?: string;
+    url?: string;
+    salt?: string;
+}
+export interface PayX402WithSolanaResult {
+    /** 可直接写入 `PAYMENT-SIGNATURE` 头 */
+    header: string;
+    payload: X402SolanaPaymentPayload;
+    /** 链上付款交易签名（= payload.payload.txHash） */
+    txHash: string;
+    payment: X402SolanaPayment;
+    accept: X402Accept;
+}
+/** base58 编码（仅用于把 64B ed25519 签名转成 wire 形态）。 */
+export declare function encodeBase58(bytes: Uint8Array): string;
+export declare function isSolanaAccept(accept: X402Accept): boolean;
+/** 选 Solana accept：优先 exact；可按 network 精确过滤。 */
+export declare function selectSolanaAccept(challenge: X402PaymentRequired, opts?: {
+    network?: string;
+}): X402Accept;
+/** 按 accept 组装转账参数（原生 SOL）。 */
+export declare function buildSolanaX402Payment(accept: X402Accept): X402SolanaPayment;
+/** 构造待签消息（必须与 payments `buildSolanaPaymentMessage` 逐字节一致）。 */
+export declare function buildSolanaX402Message(payload: X402SolanaPaymentPayload): Uint8Array;
+/** 由链上付款结果构造未签名的 payload。 */
+export declare function buildSolanaX402Payload(args: {
+    challenge: X402PaymentRequired;
+    accepted: X402Accept;
+    txHash: string;
+    payer: string;
+    method?: string;
+    url?: string;
+    salt?: string;
+}): X402SolanaPaymentPayload;
+/**
+ * 用 Solana 会话密钥签 x402 payload，返回 base58 签名。
+ * 写入 `payload.signature` 后即可 base64 成 `PAYMENT-SIGNATURE`。
+ */
+export declare function signX402WithSolanaSession(payload: X402SolanaPaymentPayload, signer: X402SolanaSigner): Promise<string>;
+/** 把已签名的 payload 编码成 `PAYMENT-SIGNATURE` 头。 */
+export declare function encodeSolanaPaymentSignature(payload: X402SolanaPaymentPayload): string;
+/**
+ * 一次完成「链上转账 → 等确认 → x402 凭证签名」。
+ * 转账由调用方注入（可用 aa-relay `/solana/submit` 广播，gas 可垫付）。
+ */
+export declare function payX402WithSolana(params: PayX402WithSolanaParams): Promise<PayX402WithSolanaResult>;

package/dist/aa/x402-solana.js

@@ -0,0 +1,171 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// x402 v2 · Solana（verifyOnly）客户端
+//
+// 结算模型与 EVM 一致：客户端自己广播 SOL 转账，服务端只做「验签 + 链上校验 +
+// 入账」，没有 facilitator `/settle`。
+//
+// 与 payments 服务端（`protocol/x402-v2.ts`）逐字节对齐：
+//   message = ["x402-solana-v2", scheme, network, amount, asset, payTo,
+//              method, url, salt, txHash].join("\n")
+//   header  = base64(JSON({ x402Version, resource, accepted,
+//                 payload:{method,url,salt,txHash,payer}, signature }))
+//
+// EVM 用 EIP-712 把「accepted + payload」绑定到付款人；SVM 没有等价的结构化
+// 签名，改用 ed25519 对上面这条确定性消息签名，payer 由 `payload.payer` 显式给出
+// （ed25519 无法从签名恢复公钥），服务端再用该公钥验签 + 校验链上同址。
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOLANA_X402_ASSET = exports.SOLANA_X402_DOMAIN = exports.SOLANA_NETWORK_PREFIX = void 0;
+exports.encodeBase58 = encodeBase58;
+exports.isSolanaAccept = isSolanaAccept;
+exports.selectSolanaAccept = selectSolanaAccept;
+exports.buildSolanaX402Payment = buildSolanaX402Payment;
+exports.buildSolanaX402Message = buildSolanaX402Message;
+exports.buildSolanaX402Payload = buildSolanaX402Payload;
+exports.signX402WithSolanaSession = signX402WithSolanaSession;
+exports.encodeSolanaPaymentSignature = encodeSolanaPaymentSignature;
+exports.payX402WithSolana = payX402WithSolana;
+const x402_1 = require("./x402");
+/** CAIP-2 Solana network 前缀（如 `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`）。 */
+exports.SOLANA_NETWORK_PREFIX = 'solana:';
+/** Solana x402 签名域分隔标签。 */
+exports.SOLANA_X402_DOMAIN = 'x402-solana-v2';
+/** Solana 原生资产标签（与账本 `asset` 列一致，金额单位为 lamports）。 */
+exports.SOLANA_X402_ASSET = 'sol';
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+/** base58 编码（仅用于把 64B ed25519 签名转成 wire 形态）。 */
+function encodeBase58(bytes) {
+    let zeros = 0;
+    while (zeros < bytes.length && bytes[zeros] === 0)
+        zeros++;
+    const digits = [];
+    for (let i = zeros; i < bytes.length; i++) {
+        let carry = bytes[i];
+        for (let j = 0; j < digits.length; j++) {
+            carry += digits[j] << 8;
+            digits[j] = carry % 58;
+            carry = (carry / 58) | 0;
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = (carry / 58) | 0;
+        }
+    }
+    let out = '1'.repeat(zeros);
+    for (let i = digits.length - 1; i >= 0; i--)
+        out += BASE58_ALPHABET[digits[i]];
+    return out;
+}
+function isSolanaAccept(accept) {
+    return (String(accept.network ?? '').startsWith(exports.SOLANA_NETWORK_PREFIX) &&
+        String(accept.asset ?? '').toLowerCase() === exports.SOLANA_X402_ASSET);
+}
+/** 选 Solana accept：优先 exact；可按 network 精确过滤。 */
+function selectSolanaAccept(challenge, opts = {}) {
+    const matches = challenge.accepts.filter((a) => isSolanaAccept(a) && (opts.network === undefined || a.network === opts.network));
+    const pick = matches.find((a) => a.scheme === 'exact') ?? matches[0];
+    if (!pick)
+        throw new Error('[keel-sdk] no Solana accept in this x402 challenge');
+    return pick;
+}
+/** 按 accept 组装转账参数（原生 SOL）。 */
+function buildSolanaX402Payment(accept) {
+    if (!isSolanaAccept(accept)) {
+        throw new Error(`[keel-sdk] accept is not Solana native: ${accept.network}/${accept.asset}`);
+    }
+    const lamports = BigInt(accept.amount);
+    if (lamports <= 0n)
+        throw new Error('[keel-sdk] x402 amount must be > 0');
+    if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(accept.payTo)) {
+        throw new Error(`[keel-sdk] invalid Solana payTo: ${accept.payTo}`);
+    }
+    return { to: accept.payTo, lamports, asset: exports.SOLANA_X402_ASSET };
+}
+/** 构造待签消息（必须与 payments `buildSolanaPaymentMessage` 逐字节一致）。 */
+function buildSolanaX402Message(payload) {
+    const { accepted } = payload;
+    return new TextEncoder().encode([
+        exports.SOLANA_X402_DOMAIN,
+        accepted.scheme,
+        accepted.network,
+        accepted.amount,
+        accepted.asset,
+        accepted.payTo,
+        payload.payload.method,
+        payload.payload.url,
+        payload.payload.salt,
+        payload.payload.txHash,
+    ].join('\n'));
+}
+/** 由链上付款结果构造未签名的 payload。 */
+function buildSolanaX402Payload(args) {
+    return {
+        x402Version: 2,
+        resource: args.challenge.resource,
+        accepted: args.accepted,
+        payload: {
+            method: args.method ?? 'GET',
+            url: args.url ?? args.challenge.resource?.url ?? '',
+            salt: args.salt ?? `${args.txHash}:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+            txHash: args.txHash,
+            payer: args.payer,
+        },
+        signature: '',
+    };
+}
+/**
+ * 用 Solana 会话密钥签 x402 payload，返回 base58 签名。
+ * 写入 `payload.signature` 后即可 base64 成 `PAYMENT-SIGNATURE`。
+ */
+async function signX402WithSolanaSession(payload, signer) {
+    if (payload.payload.payer !== signer.publicKey) {
+        throw new Error('[keel-sdk] payload.payer does not match the signing publicKey');
+    }
+    const raw = await signer.signMessage(buildSolanaX402Message(payload));
+    const sig = typeof raw === 'string' ? raw : encodeBase58(raw);
+    if (!/^[1-9A-HJ-NP-Za-km-z]{64,88}$/.test(sig)) {
+        throw new Error('[keel-sdk] signMessage must return a 64-byte ed25519 signature');
+    }
+    return sig;
+}
+/** 把已签名的 payload 编码成 `PAYMENT-SIGNATURE` 头。 */
+function encodeSolanaPaymentSignature(payload) {
+    return (0, x402_1.toBase64)(JSON.stringify(payload));
+}
+/**
+ * 一次完成「链上转账 → 等确认 → x402 凭证签名」。
+ * 转账由调用方注入（可用 aa-relay `/solana/submit` 广播，gas 可垫付）。
+ */
+async function payX402WithSolana(params) {
+    const accept = params.accept ?? selectSolanaAccept(params.challenge);
+    const payment = buildSolanaX402Payment(accept);
+    const sent = await params.sendPayment(payment);
+    const txHash = String(sent?.signature ?? '').trim();
+    if (!/^[1-9A-HJ-NP-Za-km-z]{64,88}$/.test(txHash)) {
+        throw new Error(`[keel-sdk] sendPayment must return a base58 tx signature, got ${txHash}`);
+    }
+    const payer = String(sent.payer ?? params.signer.publicKey);
+    if (payer !== params.signer.publicKey) {
+        throw new Error('[keel-sdk] sendPayment payer differs from the x402 signing key');
+    }
+    if (params.waitForConfirmation)
+        await params.waitForConfirmation(txHash);
+    const unsigned = buildSolanaX402Payload({
+        challenge: params.challenge,
+        accepted: accept,
+        txHash,
+        payer,
+        method: params.method,
+        url: params.url,
+        salt: params.salt,
+    });
+    unsigned.signature = await signX402WithSolanaSession(unsigned, params.signer);
+    return {
+        header: encodeSolanaPaymentSignature(unsigned),
+        payload: unsigned,
+        txHash,
+        payment,
+        accept,
+    };
+}

package/dist/http.d.ts

@@ -1,6 +1,6 @@
 import type { KeelConfig } from './types';
 /** SDK 版本（契约 §5，随包版本同步）。 */
-export declare const SDK_VERSION = "2.3.2";
+export declare const SDK_VERSION = "2.4.0";
 export declare class HttpClient {
     private baseUrl;
     private headers;

package/dist/http.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpClient = exports.SDK_VERSION = void 0;
 const errors_1 = require("./errors");
 /** SDK 版本（契约 §5，随包版本同步）。 */
-exports.SDK_VERSION = '2.3.2';
+exports.SDK_VERSION = '2.4.0';
 /**
  * 钱包签名的复用时长（ms）：首次签名后在该窗口内复用，避免每个请求都触发钱包弹窗。
  * 服务端会话 TTL 为 24h，此处取 1h 留足余量。
@@ -88,7 +88,7 @@ class HttpClient {
             return { ...this.headers, ...this.walletToken.headers };
         }
         const timestamp = String(now);
-        const signature = await this.wallet.sign(`InfraX auth: ${timestamp}`);
+        const signature = await this.wallet.sign(`Keel auth: ${timestamp}`);
         const headers = {
             'x-wallet-address': this.wallet.address.toLowerCase(),
             'x-wallet-timestamp': timestamp,

package/dist/wallet/index.d.ts

@@ -1,6 +1,7 @@
 export * from './types';
 export * from './solana-account-types';
 export * from './solana-execution-types';
+export * from './solana-dex-types';
 export * from './mpc-types';
 export * from './wallet-api';
 export * from '../aa';

package/dist/wallet/index.js

@@ -20,6 +20,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./solana-account-types"), exports);
 __exportStar(require("./solana-execution-types"), exports);
+__exportStar(require("./solana-dex-types"), exports);
 __exportStar(require("./mpc-types"), exports);
 __exportStar(require("./wallet-api"), exports);
 __exportStar(require("../aa"), exports);

package/dist/wallet/solana-dex-types.d.ts

@@ -0,0 +1,136 @@
+import type { SolanaSubmitResult } from './solana-execution-types';
+/** DEX 报价（只读，不构建交易） */
+export interface SolanaDexQuoteParams {
+    chain: string;
+    inputMint: string;
+    outputMint: string;
+    /** base units（十进制整数） */
+    amount: string | number;
+    slippageBps?: number;
+}
+export interface SolanaDexQuoteResult {
+    chain: string;
+    /** Jupiter 原始报价（字段随聚合器版本变化，按需读取） */
+    quote: Record<string, unknown>;
+    inputMint: string;
+    inAmount: string;
+    outputMint: string;
+    outAmount: string;
+    otherAmountThreshold: string;
+    priceImpactPct: string;
+    slippageBps: number;
+}
+/** `ProgramInteraction` policy 安装入参（`/dex/policy` 与 `/dex/install` 通用） */
+export interface SolanaDexPolicyParams {
+    chain: string;
+    blockhash: string;
+    feePayer: string;
+    creator: string;
+    settingsPda: string;
+    transactionIndex: string | number;
+    /** policy PDA 的 u64 seed（= 调用前链上 `settings.policySeed + 1`） */
+    seed: string | number;
+    /** 作为 policy 唯一签名者的 session key 公钥 */
+    sessionKey: string;
+    rentPayer?: string;
+    accountIndex?: number;
+    /** 缺省 `[1,2,4]`（Initiate | Vote | Execute） */
+    permissions?: number[];
+    spendingLimits?: Array<{
+        mint: string;
+        /** base units（十进制整数） */
+        maxPerPeriod: string | number;
+        period?: number;
+        start?: string | number;
+        expiration?: string | number;
+    }>;
+    /** 缺省 = relay 配置里的 program 白名单（Jupiter + 直连 DEX + 辅助 program） */
+    constraints?: Array<{
+        programId: string;
+        accountConstraints?: Array<{
+            accountIndex: number;
+            pubkeys: string[];
+            owner?: string;
+        }>;
+        dataConstraints?: Array<{
+            offset: string | number;
+            value?: string;
+            operator?: number;
+        }>;
+    }>;
+    memo?: string;
+}
+/** 安装计划中的一步（未签名交易，按 `steps` 顺序签名广播） */
+export interface SolanaDexInstallStep {
+    step: 'createSettingsTransaction' | 'createProposal' | 'approveProposal' | 'executeSettingsTransaction';
+    /** 需要本地签名的公钥（base58） */
+    signers: string[];
+    instructionCount: number;
+    /** base64（v0） */
+    transaction: string;
+}
+export interface SolanaDexInstallResult {
+    chain: string;
+    policyPda: string;
+    /** 四步共用同一个 blockhash；过期未走完需重新调用 */
+    blockhash: string;
+    steps: SolanaDexInstallStep[];
+}
+export interface SolanaDexSwapParams {
+    chain: string;
+    blockhash: string;
+    feePayer: string;
+    /** policy PDA */
+    policy: string;
+    /** smart account（vault）PDA */
+    vaultPda: string;
+    sessionKey: string;
+    inputMint: string;
+    outputMint: string;
+    amount: string | number;
+    accountIndex?: number;
+    numSigners?: number;
+    slippageBps?: number;
+    wrapAndUnwrapSol?: boolean;
+    dynamicComputeUnitLimit?: boolean;
+    /**
+     * policy 创建时 `instructionsConstraints` 的顺序（programId 数组）。
+     * 缺省取 relay 配置白名单顺序；链上要求逐条指令都能映射到一条约束。
+     */
+    policyPrograms?: string[];
+}
+export interface SolanaDexSwapResult {
+    chain: string;
+    inAmount: string;
+    outAmount: string;
+    otherAmountThreshold: string;
+    priceImpactPct: string;
+    slippageBps: number;
+    innerInstructionCount: number;
+    instructionConstraintIndices: number[];
+    addressLookupTables: number;
+    transactionBytes: number;
+    /** 未签名交易（base64 v0）；签名后经 `submit` 广播才会计费 */
+    transaction: string;
+    instructionCount?: number;
+    /** 计费提示：签名后发到该端点，relay 按 fee payer 收固定服务费 */
+    billing?: {
+        endpoint: string;
+        feePayer: string;
+        feeLamports: string;
+    };
+}
+/**
+ * 本地签名回调：入参为未签名交易（base64 v0）与需要签名的公钥，
+ * 返回已签名的 base64 交易。SDK 不内置 Solana 依赖，由调用方用
+ * `@solana/web3.js`（`VersionedTransaction.deserialize` → `sign`）实现。
+ */
+export type SolanaTransactionSigner = (transaction: string, signers: string[]) => Promise<string> | string;
+/** `dexSwapAndSubmit`：一次完成「取未签名交易 → 本地签名 → 经 relay 计费广播」。 */
+export interface SolanaDexSwapAndSubmitParams extends SolanaDexSwapParams {
+    sign: SolanaTransactionSigner;
+}
+export interface SolanaDexSwapAndSubmitResult extends SolanaDexSwapResult {
+    /** relay `/submit` 的广播回执（计费发生在这里） */
+    submit: SolanaSubmitResult;
+}

package/dist/wallet/solana-dex-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/wallet/wallet-api.d.ts

@@ -3,6 +3,7 @@ import type { KeelEnvelope } from '../types';
 import type { CreateWalletParams, WalletCreated, ImportWalletParams, SignParams, SignResult, SendParams, SendResult, ChainParams, ChainResult, WalletBalanceParams, WalletBalanceResult, SessionCreateParams, SessionCreated, PaymasterInfo, PaymasterVoucherParams, PaymasterVoucher } from './types';
 import type { SolanaDeriveAccountParams, SolanaDerivedAccount, SolanaCreateAccountParams, SolanaInstallPolicyParams, SolanaCreatePolicyTransactionParams, SolanaCreateProposalParams, SolanaApproveProposalParams, SolanaExecutePolicyTransactionParams, SolanaRemovePolicyParams } from './solana-account-types';
 import type { SolanaExecutePolicyPayloadParams, SolanaCloseSettingsParams, SolanaCloseTransactionParams, SolanaExecutePolicyParams, SolanaExecuteParams, SolanaRemoveSignerParams, SolanaSubmitParams, SolanaUnsignedTransaction, SolanaSubmitResult } from './solana-execution-types';
+import type { SolanaDexQuoteParams, SolanaDexQuoteResult, SolanaDexPolicyParams, SolanaDexInstallResult, SolanaDexSwapParams, SolanaDexSwapResult, SolanaDexSwapAndSubmitParams, SolanaDexSwapAndSubmitResult } from './solana-dex-types';
 import type { MpcSendCodeParams, MpcVerifyParams, MpcBalanceParams, MpcSignMessageParams, MpcSignTypedDataParams, MpcSendTransactionParams, MpcContractCallParams, MpcContractWriteParams, MpcGasEstimateParams, MpcRegisterParams, MpcRegisterResult, MpcSolanaSignParams, MpcSolanaSignResult, MpcSolanaSendParams, MpcSolanaSendResult } from './mpc-types';
 export declare class WalletAPI {
     private http;
@@ -171,6 +172,18 @@ export declare class WalletAPI {
             execute: (p: SolanaExecuteParams) => Promise<SolanaUnsignedTransaction>;
             removeSigner: (p: SolanaRemoveSignerParams) => Promise<SolanaUnsignedTransaction>;
             submit: (p: SolanaSubmitParams) => Promise<SolanaSubmitResult>;
+            /** DEX：Jupiter 报价（只读，不构建交易）。 */
+            dexQuote: (p: SolanaDexQuoteParams) => Promise<SolanaDexQuoteResult>;
+            /** DEX：一站式 policy 安装——返回四笔未签名交易，按 `steps` 顺序本地签名广播。 */
+            dexInstallPolicy: (p: SolanaDexPolicyParams) => Promise<SolanaDexInstallResult>;
+            /** DEX：组装 ProgramInteraction swap 交易（未签名；签名后经 `submit` 广播并计费）。 */
+            dexSwap: (p: SolanaDexSwapParams) => Promise<SolanaDexSwapResult>;
+            /**
+             * DEX：一步完成 swap —— 取未签名交易 → `sign` 回调本地签名 → 经 `/submit` 广播。
+             * `sign` 由调用方提供（SDK 不内置 Solana 依赖），例如：
+             * `(b64) => { const tx = VersionedTransaction.deserialize(Buffer.from(b64, 'base64')); tx.sign([kp]); return Buffer.from(tx.serialize()).toString('base64') }`
+             */
+            dexSwapAndSubmit: (p: SolanaDexSwapAndSubmitParams) => Promise<SolanaDexSwapAndSubmitResult>;
         };
     };
     /** MPC（email 分片钱包）子域：canonical `/v1/wallet/mpc/*`。 */

package/dist/wallet/wallet-api.js

@@ -153,6 +153,24 @@ class WalletAPI {
             execute: (p) => this.http.post('/v1/wallet/session/solana/session/execute', p),
             removeSigner: (p) => this.http.post('/v1/wallet/session/solana/session/remove-signer', p),
             submit: (p) => this.http.post('/v1/wallet/session/solana/submit', p),
+            /** DEX：Jupiter 报价（只读，不构建交易）。 */
+            dexQuote: (p) => this.http.post('/v1/wallet/session/solana/dex/quote', p),
+            /** DEX：一站式 policy 安装——返回四笔未签名交易，按 `steps` 顺序本地签名广播。 */
+            dexInstallPolicy: (p) => this.http.post('/v1/wallet/session/solana/dex/install', p),
+            /** DEX：组装 ProgramInteraction swap 交易（未签名；签名后经 `submit` 广播并计费）。 */
+            dexSwap: (p) => this.http.post('/v1/wallet/session/solana/dex/swap', p),
+            /**
+             * DEX：一步完成 swap —— 取未签名交易 → `sign` 回调本地签名 → 经 `/submit` 广播。
+             * `sign` 由调用方提供（SDK 不内置 Solana 依赖），例如：
+             * `(b64) => { const tx = VersionedTransaction.deserialize(Buffer.from(b64, 'base64')); tx.sign([kp]); return Buffer.from(tx.serialize()).toString('base64') }`
+             */
+            dexSwapAndSubmit: async (p) => {
+                const { sign, ...swap } = p;
+                const built = await this.http.post('/v1/wallet/session/solana/dex/swap', swap);
+                const signed = await sign(built.transaction, [...new Set([swap.feePayer, swap.sessionKey])]);
+                const submit = await this.http.post('/v1/wallet/session/solana/submit', { chain: swap.chain, transaction: signed });
+                return { ...built, submit };
+            },
         },
     };
     /** MPC（email 分片钱包）子域：canonical `/v1/wallet/mpc/*`。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keelcodes/sdk",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "description": "Keel SDK — unified access to payment / wallet / data / account modules over https://keel.codes",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",