Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix: disable deposits for unsignable agent wallets

ni3a84f244000545
diff --git a/api/agents/solana-wallet.js b/api/agents/solana-wallet.js
index fbea35911..b698fb5b7 100644
--- a/api/agents/solana-wallet.js
+++ b/api/agents/solana-wallet.js
@@ -155,6 +155,29 @@ async function resolveAuth(req) {
return null;
}
+// A deposit address is safe to advertise only when the stored custodial key can
+// actually sign for that exact address. Balance reads alone cannot prove this:
+// an address whose encryption key was retired still has a perfectly valid,
+// publicly-readable on-chain balance. Keep this verdict in the API so every
+// funding surface can fail closed instead of independently guessing from the
+// presence of an address.
+async function walletSigningStatus(meta = {}) {
+ if (!meta.solana_address) return { signable: false, reason: 'wallet_missing' };
+ if (!meta.encrypted_solana_secret) return { signable: false, reason: 'key_missing' };
+ try {
+ const keypair = await recoverSolanaAgentKeypair(meta.encrypted_solana_secret);
+ if (keypair.publicKey.toBase58() !== meta.solana_address) {
+ return { signable: false, reason: 'key_mismatch' };
+ }
+ return { signable: true, reason: null };
+ } catch (e) {
+ return {
+ signable: false,
+ reason: isUnrecoverableSecret(e) ? 'key_retired' : 'key_error',
+ };
+ }
+}
+
// ── activity ──────────────────────────────────────────────────────────────────
async function handleActivity(req, res, id) {
@@ -309,10 +332,14 @@ async function handlePublicWalletRead(req, res, id) {
wallet: null,
balance: null,
chain: 'solana',
+ deposits_enabled: false,
+ deposits_disabled_reason: 'wallet_missing',
},
});
}
+ const signing = await walletSigningStatus(row.meta);
+
let lamports = null;
let balanceError = null;
const balCacheKey = `sol:bal:${address}:${net}`;
@@ -343,6 +370,8 @@ async function handlePublicWalletRead(req, res, id) {
chain: 'solana',
network: net,
lamports,
+ deposits_enabled: signing.signable,
+ ...(!signing.signable ? { deposits_disabled_reason: signing.reason } : {}),
...(balanceError ? { balance_error: balanceError } : {}),
},
});
@@ -470,24 +499,17 @@ async function handleWallet(req, res, id) {
? await _reverseSnsCached(meta.solana_address)
: null;
- // Can we still SIGN for this wallet, or are we showing the owner a balance they
+ // Can we still SIGN for this wallet, or are we showing a balance whose funds
// can never move? A custodial secret sealed under a retired WALLET_ENCRYPTION_KEY
// still reads back a perfectly healthy on-chain balance, so the wallet card looked
// identical to a working one right up until the owner typed an amount, confirmed a
// withdrawal, and got a 500. Measured 2026-08-01: two customer agents holding
// 0.35 SOL are in exactly that state. The check is a local AES-GCM attempt on one
- // record (no network, sub-millisecond) and runs only on the owner's own read.
- let signable = null;
- let signableReason = null;
- if (meta.encrypted_solana_secret) {
- try {
- await recoverSolanaAgentKeypair(meta.encrypted_solana_secret);
- signable = true;
- } catch (e) {
- signable = false;
- signableReason = isUnrecoverableSecret(e) ? 'key_retired' : 'key_error';
- }
- }
+ // record (no network, sub-millisecond). The public read exposes only the deposit
+ // safety verdict; the owner read additionally exposes the signing verdict.
+ const signing = await walletSigningStatus(meta);
+ const signable = signing.signable;
+ const signableReason = signing.reason;
return json(res, req.method === 'POST' ? 201 : 200, {
data: {
@@ -498,6 +520,8 @@ async function handleWallet(req, res, id) {
...(balanceError ? { balance_error: balanceError } : {}),
signable,
...(signableReason ? { signable_reason: signableReason } : {}),
+ deposits_enabled: signable,
+ ...(!signable ? { deposits_disabled_reason: signableReason } : {}),
vanity_prefix: meta.solana_vanity_prefix || null,
vanity_suffix: meta.solana_vanity_suffix || null,
source: meta.solana_wallet_source || (meta.encrypted_solana_secret ? 'generated' : null),
diff --git a/docs/agent-wallets.md b/docs/agent-wallets.md
index d6033eebf..d89f9549d 100644
--- a/docs/agent-wallets.md
+++ b/docs/agent-wallets.md
@@ -69,7 +69,9 @@ The **Agent Wallet Hub** lives at `/agent/:id/wallet`. Owners see all 23 section
Key endpoints:
-- `GET /api/agents/:id/solana` — address, live balance (public)
+- `GET /api/agents/:id/solana` — address, live balance, and `deposits_enabled`
+ safety verdict (public). Funding UIs must require `deposits_enabled === true`;
+ a missing, false, or unreadable verdict is not safe to fund.
- `GET /api/agents/:id/solana/activity` — parsed transaction feed (owner only)
- `GET`/`PUT /api/agents/:id/solana/limits` — read and set the spend policy
- `POST /api/agents/:id/solana/withdraw` — sweep an asset out
diff --git a/src/agent-wallet-hub/tabs/deposit.js b/src/agent-wallet-hub/tabs/deposit.js
index 481ec09d2..4e06a86b1 100644
--- a/src/agent-wallet-hub/tabs/deposit.js
+++ b/src/agent-wallet-hub/tabs/deposit.js
@@ -135,6 +135,11 @@ registerWalletTab({
const state = {
loaded: false,
address: ctx.agent?.solana_address || ctx.agent?.meta?.solana_address || null,
+ // Funding is enabled only after the API proves that the platform can
+ // sign for this exact address. Unknown must fail closed: otherwise a
+ // stale address remains fundable during an API error or old deployment.
+ depositsEnabled: null,
+ depositsDisabledReason: null,
amount: '', // user-entered SOL amount for the QR/deep-link
amountError: false,
// Live confirmation tracking.
@@ -271,6 +276,41 @@ registerWalletTab({
return;
}
+ if (state.depositsEnabled !== true) {
+ const reason = state.depositsDisabledReason;
+ const knownKeyFailure = ['key_retired', 'key_missing', 'key_mismatch', 'key_error'].includes(reason);
+ panel.innerHTML = `
+ <div class="awh-card">
+ <div class="awh-dep-who">
+ ${avatar ? `<img class="awh-dep-who-av" src="${escapeHtml(avatar)}" alt="" loading="lazy" data-fallback="remove" />` : ''}
+ <div class="awh-dep-who-txt"><strong>Deposits are disabled for ${escapeHtml(agentName)}.</strong></div>
+ </div>
+ <div class="awh-err" role="alert">
+ <strong>Do not send funds to this wallet.</strong>
+ <div class="why" style="text-transform:none; margin-top:6px; line-height:1.5;">
+ ${knownKeyFailure
+ ? 'The platform cannot authorize outgoing transactions from this address. Existing on-chain funds remain visible, but sending more would leave those funds immovable.'
+ : 'The platform could not verify that it can authorize outgoing transactions from this address. Funding controls stay disabled until that safety check succeeds.'}
+ </div>
+ </div>
+ <div class="awh-dep-label" style="margin-top:12px">Disabled wallet address</div>
+ <div class="awh-dep-addr" title="${escapeHtml(state.address)}">${escapeHtml(state.address)}</div>
+ <div class="awh-dep-actions" style="margin-top:12px">
+ <a class="awh-btn" href="${escapeHtml(explorerAddressUrl(state.address, net))}" target="_blank" rel="noopener">View existing funds ↗</a>
+ ${ctx.isOwner ? `<a class="awh-btn" href="/support?topic=wallet-key&agent=${encodeURIComponent(ctx.agentId)}">Contact support</a>` : ''}
+ <button class="awh-btn" type="button" data-act="reload">Re-check</button>
+ </div>
+ </div>`;
+ panel.querySelector('[data-act="reload"]')?.addEventListener('click', () => {
+ state.loaded = false;
+ state.depositsEnabled = null;
+ state.depositsDisabledReason = null;
+ render();
+ loadInitial();
+ });
+ return;
+ }
+
const uri = solanaUri();
panel.innerHTML = `
<div class="awh-card">
@@ -394,18 +434,24 @@ registerWalletTab({
} catch {
return { ok: false };
}
- if (!r) return { ok: false };
- if (r.status === 'forbidden') return { ok: false, forbidden: true };
- if (r.status === 'none') return { ok: true, address: null, sol: null };
- if (r.status === 'error') return { ok: false };
- if (r.data?.balance_error) return { ok: false };
- return { ok: true, address: r.data?.address || null, sol: r.data?.sol ?? null };
+ if (!r) return { ok: false, depositsEnabled: false, depositsDisabledReason: 'health_unavailable' };
+ if (r.status === 'forbidden') return { ok: false, forbidden: true, depositsEnabled: false, depositsDisabledReason: 'health_unavailable' };
+ if (r.status === 'none') return { ok: true, address: null, sol: null, depositsEnabled: false, depositsDisabledReason: 'wallet_missing' };
+ if (r.status === 'error') return { ok: false, depositsEnabled: false, depositsDisabledReason: 'health_unavailable' };
+ const health = {
+ depositsEnabled: r.data?.deposits_enabled === true,
+ depositsDisabledReason: r.data?.deposits_disabled_reason || (r.data?.deposits_enabled === true ? null : 'health_unavailable'),
+ };
+ if (r.data?.balance_error) return { ok: false, address: r.data?.address || null, ...health };
+ return { ok: true, address: r.data?.address || null, sol: r.data?.sol ?? null, ...health };
}
async function loadInitial() {
const res = await readBalance();
+ state.depositsEnabled = res.depositsEnabled === true;
+ state.depositsDisabledReason = res.depositsDisabledReason || null;
if (res.ok) {
- if (res.address) state.address = res.address;
+ state.address = res.address;
state.balanceError = false;
if (typeof res.sol === 'number') state.baselineSol = res.sol;
} else {
@@ -420,6 +466,16 @@ registerWalletTab({
async function poll() {
if (!visible || destroyed || !state.address) return;
const res = await readBalance();
+ if (res.depositsEnabled !== true) {
+ state.depositsEnabled = false;
+ state.depositsDisabledReason = res.depositsDisabledReason || 'health_unavailable';
+ if (res.address) state.address = res.address;
+ state.balanceError = !res.ok;
+ render();
+ return;
+ }
+ state.depositsEnabled = true;
+ state.depositsDisabledReason = null;
if (!res.ok) {
if (!state.balanceError) {
state.balanceError = true;
@@ -483,6 +539,8 @@ registerWalletTab({
// A network switch resets the live-confirmation baseline for the new cluster.
detachNet = ctx.onNetworkChange(() => {
state.loaded = false;
+ state.depositsEnabled = null;
+ state.depositsDisabledReason = null;
state.baselineSol = null;
state.received = null;
state.receivedCount = 0;
diff --git a/src/agent-wallet-hub/tabs/withdraw.js b/src/agent-wallet-hub/tabs/withdraw.js
index 7a708e16e..0d95ccd8a 100644
--- a/src/agent-wallet-hub/tabs/withdraw.js
+++ b/src/agent-wallet-hub/tabs/withdraw.js
@@ -528,7 +528,7 @@ registerWalletTab({
// does not send the field leaves it undefined, which stays null here and
// keeps the form exactly as it was: this gate blocks only on a definite no.
async function loadSignable() {
- const res = await call(`/api/agents/${encodeURIComponent(ctx.agentId)}/wallet?network=${ctx.getNetwork()}`);
+ const res = await call(`/api/agents/${encodeURIComponent(ctx.agentId)}/solana?network=${ctx.getNetwork()}`);
if (destroyed || !res.ok) return;
if (res.data?.signable === false) {
state.signable = false;
diff --git a/tests/agent-wallet-deposit-tab.test.js b/tests/agent-wallet-deposit-tab.test.js
index efe7cc4c8..1a1722e36 100644
--- a/tests/agent-wallet-deposit-tab.test.js
+++ b/tests/agent-wallet-deposit-tab.test.js
@@ -82,7 +82,7 @@ describe('Deposit tab — public funding surface', () => {
});
it('renders the QR, address, copy control and who-you-are-funding header', async () => {
- fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0 } });
+ fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0, deposits_enabled: true } });
const { panel, inst } = mountTab();
inst.onShow();
await tick();
@@ -99,7 +99,7 @@ describe('Deposit tab — public funding surface', () => {
});
it('shows the calm "waiting for your first deposit" state before any funds land', async () => {
- fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0 } });
+ fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0, deposits_enabled: true } });
const { panel, inst } = mountTab();
inst.onShow();
await tick();
@@ -111,7 +111,7 @@ describe('Deposit tab — public funding surface', () => {
it('rewrites the deep-link with ?amount= when an amount is entered', async () => {
vi.useFakeTimers();
try {
- fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0 } });
+ fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0, deposits_enabled: true } });
const { panel, inst } = mountTab();
inst.onShow();
await vi.runOnlyPendingTimersAsync();
@@ -133,7 +133,7 @@ describe('Deposit tab — public funding surface', () => {
it('fires the "received" confirmation only on a real balance increase', async () => {
vi.useFakeTimers();
try {
- fetchAgentSolanaWallet.mockResolvedValueOnce({ status: 'ok', data: { address: ADDR, sol: 0 } });
+ fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0, deposits_enabled: true } });
const ctx = makeCtx();
const { panel, inst } = mountTab(ctx);
inst.onShow();
@@ -142,7 +142,7 @@ describe('Deposit tab — public funding surface', () => {
expect(ctx.toast).not.toHaveBeenCalled();
// Next poll observes a real on-chain increase.
- fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0.5 } });
+ fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0.5, deposits_enabled: true } });
await vi.advanceTimersByTimeAsync(15_000);
await vi.runOnlyPendingTimersAsync();
@@ -155,20 +155,42 @@ describe('Deposit tab — public funding surface', () => {
}
});
- it('keeps the address + QR usable and shows a paused state when the RPC is unreachable', async () => {
+ it('fails closed without funding controls when wallet health cannot be verified', async () => {
fetchAgentSolanaWallet.mockResolvedValue({ status: 'error', error: 'rpc down' });
const { panel, inst } = mountTab();
inst.onShow();
await tick();
- // Address comes from the agent record, so funding still works.
+ // The address may remain visible for identification, but it cannot be copied,
+ // encoded in a QR/deep-link, or tipped until the API proves it is signable.
expect(panel.textContent).toContain(ADDR);
- expect(panel.querySelector('a.awh-dep-qr svg')).toBeTruthy();
- expect(panel.querySelector('.awh-dep-status[data-state="paused"]')).toBeTruthy();
+ expect(panel.textContent).toMatch(/Do not send funds/i);
+ expect(panel.querySelector('a.awh-dep-qr')).toBeNull();
+ expect(panel.querySelector('[data-host="deeplink"]')).toBeNull();
+ expect(panel.querySelector('[data-act="copy"]')).toBeNull();
+ expect(panel.querySelector('[data-act="tip"]')).toBeNull();
+ inst.destroy();
+ });
+
+ it('removes every funding affordance for a retired-key wallet', async () => {
+ fetchAgentSolanaWallet.mockResolvedValue({
+ status: 'ok',
+ data: { address: ADDR, sol: 1, deposits_enabled: false, deposits_disabled_reason: 'key_retired' },
+ });
+ const { panel, inst } = mountTab();
+ inst.onShow();
+ await tick();
+
+ expect(panel.textContent).toMatch(/Deposits are disabled/i);
+ expect(panel.textContent).toMatch(/Do not send funds/i);
+ expect(panel.querySelector('a.awh-dep-qr')).toBeNull();
+ expect(panel.querySelector('[data-host="deeplink"]')).toBeNull();
+ expect(panel.querySelector('[data-act="copy"]')).toBeNull();
+ expect(panel.querySelector('[data-act="tip"]')).toBeNull();
inst.destroy();
});
it('never throws or blanks the panel on an extreme agent name (QR stays scannable)', async () => {
- fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0 } });
+ fetchAgentSolanaWallet.mockResolvedValue({ status: 'ok', data: { address: ADDR, sol: 0, deposits_enabled: true } });
const longName = '🚀'.repeat(300); // emoji → 4 bytes each, far past QR capacity
const ctx = makeCtx({ agent: { id: 'agent-1', name: longName, solana_address: ADDR } });
const { panel, inst } = mountTab(ctx);
diff --git a/tests/api/solana-wallet-balance.test.js b/tests/api/solana-wallet-balance.test.js
index aa42fcb61..d91598a44 100644
--- a/tests/api/solana-wallet-balance.test.js
+++ b/tests/api/solana-wallet-balance.test.js
@@ -16,6 +16,7 @@ const addr = () => Keypair.generate().publicKey.toBase58();
// Shared, mutable RPC stub state — defined before vi.mock so the (lazy) mock
// factory closes over it, matching the pattern in solana-wallet-import.test.js.
const rpcState = { lamports: 0, calls: 0, err: null };
+const keyState = { err: null, addressOverride: null };
vi.mock('../../api/_lib/auth.js', () => ({
getSessionUser: vi.fn(async () => null),
@@ -47,11 +48,15 @@ vi.mock('../../api/_lib/agent-pumpfun.js', () => {
return rpcState.lamports;
},
});
- return { solanaConnection: () => conn(), solanaPublicConnection: () => conn() };
+ return { solanaConnection: () => conn(), solanaPublicConnection: () => conn(), isUnrecoverableSecret: (e) => e?.name === 'OperationError' };
});
vi.mock('../../api/_lib/agent-wallet.js', () => ({
generateSolanaAgentWallet: vi.fn(async () => ({ address: 'x', encrypted_secret: 'y' })),
+ recoverSolanaAgentKeypair: vi.fn(async (secret) => {
+ if (keyState.err) throw keyState.err;
+ return { publicKey: { toBase58: () => keyState.addressOverride || secret } };
+ }),
}));
const { default: handler } = await import('../../api/agents/solana-wallet.js');
@@ -72,7 +77,7 @@ function makeRes() {
}
async function read(address, network = 'mainnet') {
// Unique address per call keeps the shared cache from leaking across tests.
- sqlState.queue.push([{ id: 'agent-1', meta: { solana_address: address } }]);
+ sqlState.queue.push([{ id: 'agent-1', meta: { solana_address: address, encrypted_solana_secret: address } }]);
const req = makeReq(`/api/agents/agent-1/solana?network=${network}`);
const res = makeRes();
await handler(req, res, 'agent-1');
@@ -83,6 +88,8 @@ beforeEach(() => {
rpcState.lamports = 0;
rpcState.calls = 0;
rpcState.err = null;
+ keyState.err = null;
+ keyState.addressOverride = null;
sqlState.queue = [];
});
@@ -94,6 +101,7 @@ describe('GET /api/agents/:id/solana — public balance read', () => {
expect(body.data.balance).toBe(2.5);
expect(body.data.lamports).toBe(2_500_000_000);
expect(body.data.balance_error).toBeUndefined();
+ expect(body.data.deposits_enabled).toBe(true);
});
it('surfaces balance_error=rpc_rate_limited when the RPC 429s on every attempt', async () => {
@@ -123,4 +131,19 @@ describe('GET /api/agents/:id/solana — public balance read', () => {
expect(second.body.data.balance).toBe(1);
expect(rpcState.calls).toBe(callsAfterFirst); // no additional RPC call
});
+
+ it('disables deposits when the custodial key is retired', async () => {
+ keyState.err = Object.assign(new Error('decrypt failed'), { name: 'OperationError' });
+ const { status, body } = await read(addr());
+ expect(status).toBe(200);
+ expect(body.data.deposits_enabled).toBe(false);
+ expect(body.data.deposits_disabled_reason).toBe('key_retired');
+ });
+
+ it('disables deposits when the recovered key does not own the advertised address', async () => {
+ keyState.addressOverride = addr();
+ const { body } = await read(addr());
+ expect(body.data.deposits_enabled).toBe(false);
+ expect(body.data.deposits_disabled_reason).toBe('key_mismatch');
+ });
});