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.

feat(actions): ship tip-an-agent and buy-its-coin Solana Blinks

nirholasc26b05f613f7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index da1946a44..da766353c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,6 +29,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **See what a Forge generation costs before you press Generate**: The Forge page now shows a live cost line for the tier, engine and options you picked, read from the same pricing code that bills you, with nothing spent. A pay-to-keep mode (free preview, pay in $THREE to download, holders keep free) is built and switched off, so downloads stay free until it is turned on. (`/docs/forge`) `[feature, docs]`
- **See what a prediction strategy would have earned before it trades**: Agent Predictions records every strategy decision at the live order-book price in shadow mode, marks it at resolution, and shows shadow beside live results. A fee-aware scanner reads Solana event contracts for YES plus NO pairs under $1. Live stays owner-only. (`/agent-predictions`) `[feature]`
- **Skills are scanned for hidden behaviour before they are listed**: Every marketplace skill version is now checked for secret access, calls to hosts it never declared, hidden or obfuscated code and instructions that skip the owner's confirmation. Clean skills list as before, suspicious ones are held for a moderator, and dangerous ones are refused. Authors see the file, the line and how to fix each finding in the publish form, and the existing catalog was rescanned. (`/docs/skill-supply-scan`) `[security, feature, docs]`
+- **Two new Solana Blinks: tip an agent, buy its coin**: Any agent's profile link now unfurls as a Blink in X and Blink-aware wallets with a one-tap tip (SOL or $THREE, straight to the agent's own wallet) and, for agents that launched a mainnet coin, a one-tap Jupiter-routed buy. Both build unsigned transactions only; the wallet signs. (`/docs/api-reference`) `[feature]`
## 2026-10-23
diff --git a/api/actions/agent-buy-coin.js b/api/actions/agent-buy-coin.js
new file mode 100644
index 000000000..48acf7a6a
--- /dev/null
+++ b/api/actions/agent-buy-coin.js
@@ -0,0 +1,178 @@
+// Solana Blink: "Buy this agent's coin"
+//
+// GET /api/actions/agent-buy-coin?agent=<uuid>
+// → ActionGetResponse: title, description, icon, preset SOL-amount + free-entry buttons
+//
+// POST /api/actions/agent-buy-coin?agent=<uuid>
+// Body: { "account": "<wallet pubkey>", "amount": <SOL amount> }
+// → ActionPostResponse: base64 VersionedTransaction (unsigned Jupiter swap, SOL -> mint)
+//
+// The mint is resolved at runtime from the agent's own most recent mainnet
+// pump.fun launch (pump_agent_mints), never from a caller-supplied parameter:
+// this is the platform's own launch directory, the CLAUDE.md commit-gate
+// exception for "render coins users launched through three.ws from the
+// platform's own launch records at runtime", not an endorsement of any coin.
+
+import { cors, json, error, readJson, wrap } from '../_lib/http.js';
+import { solanaConnection } from '../_lib/solana/connection.js';
+import { env } from '../_lib/env.js';
+import { sql } from '../_lib/db.js';
+import { isUuid } from '../_lib/validate.js';
+import { cdnUrlOrNull } from '../_lib/r2.js';
+import { buildSwapTransaction, MAX_UI_AMOUNT } from '../_lib/custody/builders.js';
+
+export const maxDuration = 10;
+
+const SOLANA_MAINNET_GENESIS = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
+const ACTION_VERSION = '2.1.3';
+const SOL_MINT = 'So11111111111111111111111111111111111111112';
+const SOL_PRESETS = [0.1, 0.5, 1];
+
+function setActionVersionHeaders(res) {
+ res.setHeader('x-action-version', ACTION_VERSION);
+ res.setHeader('x-blockchain-ids', SOLANA_MAINNET_GENESIS);
+}
+
+function exposeActionHeaders(res) {
+ res.setHeader(
+ 'access-control-expose-headers',
+ 'x-action-version, x-blockchain-ids, x-payment-response, x-payment-network, x-payment-tx, link',
+ );
+}
+
+// Blink clients render ActionError.message, not our standard error envelope, so
+// action errors carry both shapes.
+function actionError(res, status, code, message) {
+ return error(res, status, code, message, { message });
+}
+
+async function findAgentAndCoin(agentId) {
+ const [agent] = await sql`
+ select i.id, i.name, a.thumbnail_key as avatar_thumbnail_key
+ from agent_identities i
+ left join avatars a on a.id = i.avatar_id and a.deleted_at is null
+ where i.id = ${agentId} and i.deleted_at is null
+ limit 1
+ `;
+ if (!agent) return { agent: null, coin: null };
+
+ const [coin] = await sql`
+ select mint, name, symbol
+ from pump_agent_mints
+ where agent_id = ${agentId} and network = 'mainnet'
+ order by created_at desc
+ limit 1
+ `;
+ return { agent, coin: coin || null };
+}
+
+export default wrap(async (req, res) => {
+ setActionVersionHeaders(res);
+ if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
+ exposeActionHeaders(res);
+
+ if (req.method !== 'GET' && req.method !== 'POST') {
+ return actionError(res, 405, 'method_not_allowed', 'GET or POST required');
+ }
+
+ const url = new URL(req.url, 'http://x');
+ const agentId = url.searchParams.get('agent') || '';
+ if (!isUuid(agentId)) {
+ return actionError(res, 400, 'bad_request', 'agent must be a valid agent id');
+ }
+
+ const { agent, coin } = await findAgentAndCoin(agentId).catch(() => ({ agent: null, coin: null }));
+ if (!agent) return actionError(res, 404, 'not_found', 'That agent is not available.');
+ if (!coin) return actionError(res, 404, 'not_found', 'This agent has not launched a coin.');
+
+ if (req.method === 'GET') return handleGet(res, agent, coin);
+ return handlePost(req, res, agent, coin);
+});
+
+function handleGet(res, agent, coin) {
+ const agentName = typeof agent.name === 'string' ? agent.name.trim().slice(0, 60) : 'this agent';
+ const symbol = typeof coin.symbol === 'string' && coin.symbol.trim() ? coin.symbol.trim().slice(0, 20) : 'its coin';
+ const icon = cdnUrlOrNull(agent.avatar_thumbnail_key) || `${env.APP_ORIGIN}/logo.png`;
+ const baseHref = `/api/actions/agent-buy-coin?agent=${encodeURIComponent(agent.id)}`;
+
+ return json(res, 200, {
+ type: 'action',
+ icon,
+ label: `Buy ${symbol}`,
+ title: `Buy ${symbol}`,
+ description: `Swap SOL for ${symbol}, ${agentName}'s coin on three.ws, via a Jupiter-routed trade.`,
+ links: {
+ actions: [
+ ...SOL_PRESETS.map((amount) => ({
+ type: 'transaction',
+ label: `Buy with ${amount} SOL`,
+ href: `${baseHref}&amount=${amount}`,
+ })),
+ {
+ type: 'transaction',
+ label: 'Custom amount',
+ href: `${baseHref}&amount={amount}`,
+ parameters: [{ name: 'amount', label: 'Amount (SOL)', type: 'number' }],
+ },
+ ],
+ },
+ }, { 'cache-control': 'public, max-age=60, s-maxage=300' });
+}
+
+async function handlePost(req, res, agent, coin) {
+ let body;
+ try {
+ body = await readJson(req, 4_000);
+ } catch (e) {
+ return actionError(res, 400, 'bad_request', e.message);
+ }
+
+ const account = typeof body?.account === 'string' ? body.account.trim() : '';
+ if (!account) return actionError(res, 400, 'bad_request', 'account is required');
+
+ const url = new URL(req.url, 'http://x');
+ const rawAmount = body?.amount ?? url.searchParams.get('amount');
+ const amount = Number(rawAmount);
+ if (!Number.isFinite(amount) || amount <= 0 || amount > MAX_UI_AMOUNT) {
+ return actionError(res, 400, 'bad_request', 'amount must be a positive number');
+ }
+
+ const { PublicKey } = await import('@solana/web3.js');
+ let payer;
+ try {
+ payer = new PublicKey(account);
+ // A curve-off point is a PDA: it has no private key, so a transaction
+ // built for it can never be signed. Reject it here rather than handing
+ // the wallet a transaction it will fail on.
+ if (!PublicKey.isOnCurve(payer.toBytes())) throw new Error('off-curve');
+ } catch {
+ return actionError(res, 400, 'bad_request', 'invalid account pubkey');
+ }
+
+ const connection = solanaConnection({ network: 'mainnet', commitment: 'confirmed' });
+
+ let built;
+ try {
+ built = await buildSwapTransaction({
+ connection,
+ sender: account,
+ inputMint: SOL_MINT,
+ outputMint: coin.mint,
+ amount,
+ slippageBps: 50,
+ });
+ } catch (err) {
+ const status = err?.status || 500;
+ if (status >= 500) return actionError(res, 503, 'rpc_unavailable', `could not build the swap transaction: ${err?.message || 'upstream error'}`);
+ return actionError(res, status, err?.code || 'bad_request', err?.message || 'could not build the swap transaction');
+ }
+
+ const txBase64 = Buffer.from(built.transaction.serialize()).toString('base64');
+ const symbol = typeof coin.symbol === 'string' && coin.symbol.trim() ? coin.symbol.trim() : 'the coin';
+
+ return json(res, 200, {
+ type: 'transaction',
+ transaction: txBase64,
+ message: `Swap built. Sign to buy ${symbol} on three.ws.`,
+ }, { 'cache-control': 'no-store' });
+}
diff --git a/api/actions/agent-tip.js b/api/actions/agent-tip.js
new file mode 100644
index 000000000..eb9fdf0f9
--- /dev/null
+++ b/api/actions/agent-tip.js
@@ -0,0 +1,181 @@
+// Solana Blink: "Tip this agent"
+//
+// GET /api/actions/agent-tip?agent=<uuid>&token=SOL|THREE
+// → ActionGetResponse: title, description, icon, preset-amount + free-entry buttons
+//
+// POST /api/actions/agent-tip?agent=<uuid>&token=SOL|THREE
+// Body: { "account": "<wallet pubkey>", "amount": <number> }
+// → ActionPostResponse: base64 VersionedTransaction (unsigned SOL/$THREE transfer)
+//
+// Shares its unsigned-transaction builder (buildTransferTransaction) and its
+// envelope/header pattern with api/actions/avatar.js. The recipient is always
+// the agent's own Solana address: the caller never supplies a destination.
+
+import { cors, json, error, readJson, wrap } from '../_lib/http.js';
+import { solanaConnection } from '../_lib/solana/connection.js';
+import { env } from '../_lib/env.js';
+import { sql } from '../_lib/db.js';
+import { isUuid } from '../_lib/validate.js';
+import { cdnUrlOrNull } from '../_lib/r2.js';
+import { getOrCreateAgentSolanaWallet } from '../_lib/agent-wallet.js';
+import { buildTransferTransaction, MAX_UI_AMOUNT } from '../_lib/custody/builders.js';
+
+export const maxDuration = 10;
+
+const SOLANA_MAINNET_GENESIS = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
+const ACTION_VERSION = '2.1.3';
+const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
+const SOL_PRESETS = [0.01, 0.1, 1];
+const THREE_PRESETS = [1000, 5000, 10000];
+
+function setActionVersionHeaders(res) {
+ res.setHeader('x-action-version', ACTION_VERSION);
+ res.setHeader('x-blockchain-ids', SOLANA_MAINNET_GENESIS);
+}
+
+function exposeActionHeaders(res) {
+ res.setHeader(
+ 'access-control-expose-headers',
+ 'x-action-version, x-blockchain-ids, x-payment-response, x-payment-network, x-payment-tx, link',
+ );
+}
+
+// Blink clients render ActionError.message, not our standard error envelope, so
+// action errors carry both shapes.
+function actionError(res, status, code, message) {
+ return error(res, status, code, message, { message });
+}
+
+async function findAgent(agentId) {
+ const [row] = await sql`
+ select i.id, i.name, a.thumbnail_key as avatar_thumbnail_key
+ from agent_identities i
+ left join avatars a on a.id = i.avatar_id and a.deleted_at is null
+ where i.id = ${agentId} and i.deleted_at is null
+ limit 1
+ `;
+ return row || null;
+}
+
+export default wrap(async (req, res) => {
+ setActionVersionHeaders(res);
+ if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
+ exposeActionHeaders(res);
+
+ if (req.method !== 'GET' && req.method !== 'POST') {
+ return actionError(res, 405, 'method_not_allowed', 'GET or POST required');
+ }
+
+ const url = new URL(req.url, 'http://x');
+ const agentId = url.searchParams.get('agent') || '';
+ if (!isUuid(agentId)) {
+ return actionError(res, 400, 'bad_request', 'agent must be a valid agent id');
+ }
+
+ const tokenParam = (url.searchParams.get('token') || 'SOL').toUpperCase();
+ if (tokenParam !== 'SOL' && tokenParam !== 'THREE') {
+ return actionError(res, 400, 'bad_request', 'token must be "SOL" or "THREE"');
+ }
+
+ const agent = await findAgent(agentId).catch(() => null);
+ if (!agent) return actionError(res, 404, 'not_found', 'That agent is not available.');
+
+ if (req.method === 'GET') return handleGet(res, agent, tokenParam);
+ return handlePost(req, res, agent, tokenParam);
+});
+
+function handleGet(res, agent, token) {
+ const name = typeof agent.name === 'string' ? agent.name.trim().slice(0, 60) : 'this agent';
+ const icon = cdnUrlOrNull(agent.avatar_thumbnail_key) || `${env.APP_ORIGIN}/logo.png`;
+ const unit = token === 'THREE' ? '$THREE' : 'SOL';
+ const presets = token === 'THREE' ? THREE_PRESETS : SOL_PRESETS;
+ const baseHref = `/api/actions/agent-tip?agent=${encodeURIComponent(agent.id)}&token=${token}`;
+
+ return json(res, 200, {
+ type: 'action',
+ icon,
+ label: `Tip ${unit}`,
+ title: `Tip ${name}`,
+ description: `Send ${unit} straight to ${name}'s own Solana wallet on three.ws.`,
+ links: {
+ actions: [
+ ...presets.map((amount) => ({
+ type: 'transaction',
+ label: `Tip ${amount} ${unit}`,
+ href: `${baseHref}&amount=${amount}`,
+ })),
+ {
+ type: 'transaction',
+ label: 'Custom amount',
+ href: `${baseHref}&amount={amount}`,
+ parameters: [{ name: 'amount', label: `Amount (${unit})`, type: 'number' }],
+ },
+ ],
+ },
+ }, { 'cache-control': 'public, max-age=60, s-maxage=300' });
+}
+
+async function handlePost(req, res, agent, token) {
+ let body;
+ try {
+ body = await readJson(req, 4_000);
+ } catch (e) {
+ return actionError(res, 400, 'bad_request', e.message);
+ }
+
+ const account = typeof body?.account === 'string' ? body.account.trim() : '';
+ if (!account) return actionError(res, 400, 'bad_request', 'account is required');
+
+ const url = new URL(req.url, 'http://x');
+ const rawAmount = body?.amount ?? url.searchParams.get('amount');
+ const amount = Number(rawAmount);
+ if (!Number.isFinite(amount) || amount <= 0 || amount > MAX_UI_AMOUNT) {
+ return actionError(res, 400, 'bad_request', 'amount must be a positive number');
+ }
+
+ const { PublicKey } = await import('@solana/web3.js');
+ let payer;
+ try {
+ payer = new PublicKey(account);
+ // A curve-off point is a PDA: it has no private key, so a transaction
+ // built for it can never be signed. Reject it here rather than handing
+ // the wallet a transaction it will fail on.
+ if (!PublicKey.isOnCurve(payer.toBytes())) throw new Error('off-curve');
+ } catch {
+ return actionError(res, 400, 'bad_request', 'invalid account pubkey');
+ }
+
+ let recipient;
+ try {
+ ({ address: recipient } = await getOrCreateAgentSolanaWallet(agent.id));
+ } catch (err) {
+ return actionError(res, 404, 'not_found', `could not resolve this agent's wallet: ${err?.message || 'unknown error'}`);
+ }
+
+ const connection = solanaConnection({ network: 'mainnet', commitment: 'confirmed' });
+
+ let built;
+ try {
+ built = await buildTransferTransaction({
+ connection,
+ sender: account,
+ recipient,
+ amount,
+ token: token === 'THREE' ? THREE_MINT : 'SOL',
+ memo: `tip:${agent.id}`,
+ network: 'mainnet',
+ });
+ } catch (err) {
+ const status = err?.status || 500;
+ if (status >= 500) return actionError(res, 503, 'rpc_unavailable', `could not build the tip transaction: ${err?.message || 'upstream error'}`);
+ return actionError(res, status, err?.code || 'bad_request', err?.message || 'could not build the tip transaction');
+ }
+
+ const txBase64 = Buffer.from(built.transaction.serialize()).toString('base64');
+
+ return json(res, 200, {
+ type: 'transaction',
+ transaction: txBase64,
+ message: `Tip sent to ${agent.name || 'this agent'}. Thank you for supporting them on three.ws.`,
+ }, { 'cache-control': 'no-store' });
+}
diff --git a/data/changelog.json b/data/changelog.json
index f830431f5..5629365e9 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,15 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-24",
+ "title": "Two new Solana Blinks: tip an agent, buy its coin",
+ "summary": "Any agent's profile link now unfurls as a Blink in X and Blink-aware wallets with a one-tap tip (SOL or $THREE, straight to the agent's own wallet) and, for agents that launched a mainnet coin, a one-tap Jupiter-routed buy. Both build unsigned transactions only; the wallet signs.",
+ "tags": [
+ "feature"
+ ],
+ "link": "/docs/api-reference"
+ },
{
"date": "2026-10-24",
"title": "2,575 NVIDIA SimReady objects in the Object Library",
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 86b7295f7..8239c29fb 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -8372,10 +8372,11 @@ curl -s -X POST https://three.ws/api/tx/explain \
## Solana Actions API (Blinks)
-three.ws publishes a Solana Action so "Claim Your 3D Avatar" unfurls as a Blink
-card on X and in any Blink-aware wallet. `/.well-known/solana/actions.json` maps
-`/api/actions/**` for Action clients, and the card's icon is a live headless
-render of the avatar's own GLB rather than a static image.
+three.ws publishes Solana Actions so a Blink card unfurls on X and in any
+Blink-aware wallet: "Claim Your 3D Avatar", "Tip this agent", and "Buy this
+agent's coin". `/.well-known/solana/actions.json` maps `/api/actions/**` for
+Action clients. Every Action here returns an unsigned `VersionedTransaction`;
+the server never signs or broadcasts.
### Claim-avatar action
@@ -8437,6 +8438,68 @@ curl -s -X POST https://three.ws/api/actions/avatar \
---
+### Tip-an-agent action
+
+```
+GET /api/actions/agent-tip?agent=<agentId>&token=SOL|THREE
+POST /api/actions/agent-tip?agent=<agentId>&token=SOL|THREE
+```
+
+No auth required. `agent` must be a real agent id; anything else is `400
+bad_request`. `token` is optional and defaults to `SOL`; the only other allowed
+value is `THREE` (`$THREE`, `FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`). An
+unknown agent is `404 not_found`. The recipient is always the agent's own
+Solana wallet (`getOrCreateAgentSolanaWallet`); the caller never names a
+destination.
+
+The GET card offers a few preset amounts plus a free-entry amount field, per
+the Actions spec's `parameters` pattern. **POST body:** `{ "account":
+"<wallet pubkey>", "amount": <number> }` (an off-curve account is rejected
+before any transaction is built, same as the claim-avatar action above).
+**POST response:** a base64 `VersionedTransaction` carrying a single unsigned
+SOL or $THREE transfer with a `tip:<agentId>` memo, built by the same
+`buildTransferTransaction` helper every other non-custodial transfer path in
+this codebase shares.
+
+```bash
+curl -s "https://three.ws/api/actions/agent-tip?agent=<agentId>" | jq .title
+curl -s -X POST "https://three.ws/api/actions/agent-tip?agent=<agentId>" \
+ -H 'content-type: application/json' \
+ -d '{"account":"FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump","amount":0.1}' | jq -r .type
+```
+
+---
+
+### Buy-an-agent's-coin action
+
+```
+GET /api/actions/agent-buy-coin?agent=<agentId>
+POST /api/actions/agent-buy-coin?agent=<agentId>
+```
+
+No auth required. `agent` must be a real agent id; anything else is `400
+bad_request`. The mint is resolved at runtime from the agent's own most recent
+mainnet pump.fun launch (`pump_agent_mints`), never from a caller-supplied
+parameter. An unknown agent, or one that has not launched a mainnet coin, is
+`404 not_found` rather than a card with nothing to buy.
+
+The GET card offers a few preset SOL amounts plus a free-entry amount field.
+**POST body:** `{ "account": "<wallet pubkey>", "amount": <SOL amount> }`.
+**POST response:** a base64 `VersionedTransaction` carrying an unsigned
+Jupiter-routed swap from SOL into the agent's mint, built by the same
+`buildSwapTransaction` helper the agent withdraw/trade external-signer paths
+use. A route that Jupiter cannot fill answers `422 no_route` or
+`422 swap_failed` rather than a generic `500`.
+
+```bash
+curl -s "https://three.ws/api/actions/agent-buy-coin?agent=<agentId>" | jq .title
+curl -s -X POST "https://three.ws/api/actions/agent-buy-coin?agent=<agentId>" \
+ -H 'content-type: application/json' \
+ -d '{"account":"FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump","amount":0.1}' | jq -r .type
+```
+
+---
+
### Blink card icon
```
diff --git a/public/.well-known/solana/actions.json b/public/.well-known/solana/actions.json
index 17bf70103..399e4f13f 100644
--- a/public/.well-known/solana/actions.json
+++ b/public/.well-known/solana/actions.json
@@ -1,6 +1,10 @@
{
"rules": [
{ "pathPattern": "/api/actions/avatar", "apiPath": "/api/actions/avatar" },
- { "pathPattern": "/api/actions/avatar?*", "apiPath": "/api/actions/avatar?*" }
+ { "pathPattern": "/api/actions/avatar?*", "apiPath": "/api/actions/avatar?*" },
+ { "pathPattern": "/api/actions/agent-tip", "apiPath": "/api/actions/agent-tip" },
+ { "pathPattern": "/api/actions/agent-tip?*", "apiPath": "/api/actions/agent-tip?*" },
+ { "pathPattern": "/api/actions/agent-buy-coin", "apiPath": "/api/actions/agent-buy-coin" },
+ { "pathPattern": "/api/actions/agent-buy-coin?*", "apiPath": "/api/actions/agent-buy-coin?*" }
]
}
diff --git a/public/changelog-recent.json b/public/changelog-recent.json
index c7e9e830e..86705a394 100644
--- a/public/changelog-recent.json
+++ b/public/changelog-recent.json
@@ -1,11 +1,11 @@
{
- "generated_at": "2026-10-24T22:42:24.498Z",
+ "generated_at": "2026-10-24T23:12:48.053Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
- "total": 4189,
+ "total": 4190,
"complete": false,
"full_feed": "/changelog.json",
"entries": [
@@ -251,6 +251,16 @@
"docs"
]
},
+ {
+ "date": "2026-10-24",
+ "type": "update",
+ "title": "Two new Solana Blinks: tip an agent, buy its coin",
+ "summary": "Any agent's profile link now unfurls as a Blink in X and Blink-aware wallets with a one-tap tip (SOL or $THREE, straight to the agent's own wallet) and, for agents that launched a mainnet coin, a one-tap Jupiter-routed buy. Both build unsigned transactions only; the wallet signs.",
+ "link": "/docs/api-reference",
+ "tags": [
+ "feature"
+ ]
+ },
{
"date": "2026-10-23",
"type": "launch",
@@ -1553,17 +1563,6 @@
"tags": [
"feature"
]
- },
- {
- "date": "2026-10-12",
- "type": "update",
- "title": "Every generated and purchased model now ships with a signed provenance credential, free, by default",
- "summary": "Content credentials (specs/PROVENANCE_3D.md) used to be an on-demand, Claude-track action: you had to call anchor_provenance to get one. Now every GLB the Forge produces, across every generation lane (free NIM, Forge Pro, rigged avatars, self-host TRELLIS/Hunyuan, async GCP workers), gets an ed25519-signed content credential the moment it's materialized, and every first download of a paid asset from the x402 asset bazaar gets one too, with the hash and a verify link returned right in the download response. Signing and storage are free and local, no Solana write and no spend, so there's nothing to gate; the separate paid anchor_provenance upgrade, which additionally commits the hash on-chain, is untouched and still available. A credential is keyed by content hash, so it's issued exactly once per file no matter how many times a lane or endpoint touches it. Model pages now show the same verified / tampered / unverified badge the 3D viewer already had, and a third party can check any model for free with GET /api/provenance. The owner can turn automatic issuance off platform-wide with PROVENANCE_AUTO_DISABLE=true; nothing else about verification changes if they do.",
- "link": "/docs/provenance",
- "tags": [
- "feature",
- "security"
- ]
}
]
}
diff --git a/public/changelog.json b/public/changelog.json
index b7a534baf..6e136de95 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-24T22:42:24.470Z",
+ "generated_at": "2026-10-24T23:12:48.028Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -248,6 +248,16 @@
"docs"
]
},
+ {
+ "date": "2026-10-24",
+ "type": "update",
+ "title": "Two new Solana Blinks: tip an agent, buy its coin",
+ "summary": "Any agent's profile link now unfurls as a Blink in X and Blink-aware wallets with a one-tap tip (SOL or $THREE, straight to the agent's own wallet) and, for agents that launched a mainnet coin, a one-tap Jupiter-routed buy. Both build unsigned transactions only; the wallet signs.",
+ "link": "/docs/api-reference",
+ "tags": [
+ "feature"
+ ]
+ },
{
"date": "2026-10-23",
"type": "launch",
diff --git a/public/changelog.xml b/public/changelog.xml
index 6ae642445..1468e24c2 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -190,6 +190,14 @@
<category>security</category>
<description>Every marketplace skill version is now checked for secret access, calls to hosts it never declared, hidden or obfuscated code and instructions that skip the owner's confirmation. Clean skills list as before, suspicious ones are held for a moderator, and dangerous ones are refused. Authors see the file, the line and how to fix each finding in the publish form, and the existing catalog was rescanned.</description>
</item>
+ <item>
+ <title>Two new Solana Blinks: tip an agent, buy its coin</title>
+ <link>https://three.ws/docs/api-reference</link>
+ <guid isPermaLink="false">2026-10-24:Two new Solana Blinks: tip an agent, buy its coin</guid>
+ <pubDate>Sat, 24 Oct 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>Any agent's profile link now unfurls as a Blink in X and Blink-aware wallets with a one-tap tip (SOL or $THREE, straight to the agent's own wallet) and, for agents that launched a mainnet coin, a one-tap Jupiter-routed buy. Both build unsigned transactions only; the wallet signs.</description>
+ </item>
<item>
<title>Builder competitions</title>
<link>https://three.ws/compete</link>
diff --git a/public/features.json b/public/features.json
index f1b93a3ba..ff748219f 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-24T22:42:24.454Z",
+ "generated_at": "2026-10-24T23:12:48.012Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
diff --git a/public/sitemap/index.html b/public/sitemap/index.html
index 0e0763c0f..cde3f79de 100644
--- a/public/sitemap/index.html
+++ b/public/sitemap/index.html
@@ -3,16 +3,16 @@
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
-<title>Sitemap · three.ws</title>
-<meta name="description" content="Human-readable index of every page on three.ws." />
+<title data-i18n="sitemap_index.meta_title">Sitemap · three.ws</title>
+<meta name="description" content="Human-readable index of every page on three.ws." data-i18n-attr="content:sitemap_index.meta_description"/>
<meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1" />
<link rel="canonical" href="https://three.ws/sitemap" />
<meta property="og:type" content="website" />
<meta property="og:site_name" content="three.ws" />
<meta property="og:locale" content="en_US" />
<meta property="og:url" content="https://three.ws/sitemap" />
-<meta property="og:title" content="Sitemap · three.ws" />
-<meta property="og:description" content="Human-readable index of every page on three.ws." />
+<meta property="og:title" content="Sitemap · three.ws" data-i18n-attr="content:sitemap_index.meta_og_title"/>
+<meta property="og:description" content="Human-readable index of every page on three.ws." data-i18n-attr="content:sitemap_index.meta_og_description"/>
<meta property="og:image" content="https://three.ws/api/page-og?s=main&amp;t=Sitemap&amp;d=Human-readable+index+of+every+page+on+three.ws.&amp;p=%2Fsitemap" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
@@ -20,8 +20,8 @@
<meta property="og:image:alt" content="Sitemap - three.ws" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="@trythreews" />
-<meta name="twitter:title" content="Sitemap · three.ws" />
-<meta name="twitter:description" content="Human-readable index of every page on three.ws." />
+<meta name="twitter:title" content="Sitemap · three.ws" data-i18n-attr="content:sitemap_index.meta_twitter_title"/>
+<meta name="twitter:description" content="Human-readable index of every page on three.ws." data-i18n-attr="content:sitemap_index.meta_twitter_description"/>
<meta name="twitter:image" content="https://three.ws/api/page-og?s=main&amp;t=Sitemap&amp;d=Human-readable+index+of+every+page+on+three.ws.&amp;p=%2Fsitemap" />
<script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"WebPage","name":"Sitemap","description":"Human-readable index of every page on three.ws.","url":"https://three.ws/sitemap","isPartOf":{"@type":"WebSite","name":"three.ws","url":"https://three.ws"},"primaryImageOfPage":"https://three.ws/api/page-og?s=main&t=Sitemap&d=Human-readable+index+of+every+page+on+three.ws.&p=%2Fsitemap"}]}</script>
<link rel="alternate" type="application/xml" title="XML sitemap" href="/sitemap.xml" />
@@ -95,16 +95,16 @@
<header><div id="nav-container"></div></header>
<main class="sm-wrap">
<div class="sm-hero">
- <h1>Sitemap</h1>
+ <h1 data-i18n="sitemap_index.sitemap">Sitemap</h1>
<p><span>1111</span> <span data-i18n="sitemap_index.pages_grouped">pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</span></p>
<div class="sm-formats">
- <a href="/everything"><code>/everything</code> · browse by goal, not by section</a>
- <a href="/sitemap.xml"><code>sitemap.xml</code> · for search engines</a>
- <a href="/llms.txt"><code>llms.txt</code> · for AI agents</a>
- <a href="/llms-full.txt"><code>llms-full.txt</code> · long form</a>
- <a href="/api/features.json"><code>features.json</code> · machine manifest</a>
- <a href="/changelog"><code>changelog</code> · what's new</a>
- <a href="/openapi.json"><code>openapi.json</code> · HTTP API</a>
+ <a href="/everything" data-i18n-html="sitemap_index.browse_by_goal_not_by_section"><code>/everything</code> · browse by goal, not by section</a>
+ <a href="/sitemap.xml" data-i18n-html="sitemap_index.for_search_engines"><code>sitemap.xml</code> · for search engines</a>
+ <a href="/llms.txt" data-i18n-html="sitemap_index.for_ai_agents"><code>llms.txt</code> · for AI agents</a>
+ <a href="/llms-full.txt" data-i18n-html="sitemap_index.long_form"><code>llms-full.txt</code> · long form</a>
+ <a href="/api/features.json" data-i18n-html="sitemap_index.machine_manifest"><code>features.json</code> · machine manifest</a>
+ <a href="/changelog" data-i18n-html="sitemap_index.what_s_new"><code>changelog</code> · what's new</a>
+ <a href="/openapi.json" data-i18n-html="sitemap_index.http_api"><code>openapi.json</code> · HTTP API</a>
</div>
</div>
<div class="sm-filter">
@@ -114,8 +114,8 @@
</div>
<p class="sm-filter-count" role="status" aria-live="polite"><span id="sm-filter-count"></span><span id="sm-filter-hint" aria-hidden="true"></span></p>
<section class="sm-new" id="sm-new" aria-labelledby="sm-new-title">
- <h2 id="sm-new-title">Newest<a class="sm-new-more" href="/changelog">full changelog &rarr;</a></h2>
- <p class="sm-section-desc">The 9 most recently launched pages, straight to the live surface.</p>
+ <h2 id="sm-new-title" data-i18n-html="sitemap_index.newestfull_changelog">Newest<a class="sm-new-more" href="/changelog">full changelog &rarr;</a></h2>
+ <p class="sm-section-desc" data-i18n="sitemap_index.the_9_most_recently_launched_pages_straight">The 9 most recently launched pages, straight to the live surface.</p>
<ul class="sm-list">
<li>
<a href="/docs/webgpu-renderer">
@@ -192,22 +192,22 @@
</ul>
</section>
<nav class="sm-toc" aria-label="Sections">
- <a href="#main">Main</a>
- <a href="#build">Build</a>
- <a href="#labs">Labs</a>
- <a href="#crypto">Crypto</a>
- <a href="#agent-tools">Agent Tools</a>
- <a href="#account">Account</a>
- <a href="#learn">Learn</a>
- <a href="#blog">Blog</a>
- <a href="#legal">Legal</a>
- <a href="#machine">Machine-readable</a>
- <a href="#news">News</a>
+ <a href="#main" data-i18n="sitemap_index.main">Main</a>
+ <a href="#build" data-i18n="sitemap_index.build">Build</a>
+ <a href="#labs" data-i18n="sitemap_index.labs">Labs</a>
+ <a href="#crypto" data-i18n="sitemap_index.crypto">Crypto</a>
+ <a href="#agent-tools" data-i18n="sitemap_index.agent_tools">Agent Tools</a>
+ <a href="#account" data-i18n="sitemap_index.account">Account</a>
+ <a href="#learn" data-i18n="sitemap_index.learn">Learn</a>
+ <a href="#blog" data-i18n="sitemap_index.blog">Blog</a>
+ <a href="#legal" data-i18n="sitemap_index.legal">Legal</a>
+ <a href="#machine" data-i18n="sitemap_index.machine_readable">Machine-readable</a>
+ <a href="#news" data-i18n="sitemap_index.news">News</a>
</nav>
<section class="sm-section" id="main">
<header>
<h2><span data-i18n="sitemap_index.section_main">Main</span><span class="sm-count" data-count>76</span></h2>
- <p class="sm-section-desc">Entry points into the product.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.entry_points_into_the_product">Entry points into the product.</p>
</header>
<ul class="sm-list">
<li>
@@ -748,7 +748,7 @@
<section class="sm-section" id="build">
<header>
<h2><span data-i18n="sitemap_index.section_build">Build</span><span class="sm-count" data-count>96</span></h2>
- <p class="sm-section-desc">Create and customize an agent.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.create_and_customize_an_agent">Create and customize an agent.</p>
</header>
<ul class="sm-list">
<li>
@@ -1429,7 +1429,7 @@
<section class="sm-section" id="labs">
<header>
<h2><span data-i18n="sitemap_index.section_labs">Labs</span><span class="sm-count" data-count>26</span></h2>
- <p class="sm-section-desc">Experimental features actively shipping. Expect fast iteration.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.experimental_features_actively_shipping_expe">Experimental features actively shipping. Expect fast iteration.</p>
</header>
<ul class="sm-list">
<li>
@@ -1620,7 +1620,7 @@
<section class="sm-section" id="crypto">
<header>
<h2><span data-i18n="sitemap_index.section_crypto">Crypto</span><span class="sm-count" data-count>174</span></h2>
- <p class="sm-section-desc">On-chain features: pay-per-call, token launches, vanity wallets.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.on_chain_features_pay_per_call_token">On-chain features: pay-per-call, token launches, vanity wallets.</p>
</header>
<ul class="sm-list">
<li>
@@ -2847,7 +2847,7 @@
<section class="sm-section" id="agent-tools">
<header>
<h2><span data-i18n="sitemap_index.section_agent-tools">Agent Tools</span><span class="sm-count" data-count>11</span></h2>
- <p class="sm-section-desc">Manage, talk to, and deploy individual agents.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.manage_talk_to_and_deploy_individual_agents">Manage, talk to, and deploy individual agents.</p>
</header>
<ul class="sm-list">
<li>
@@ -2933,7 +2933,7 @@
<section class="sm-section" id="account">
<header>
<h2><span data-i18n="sitemap_index.section_account">Account</span><span class="sm-count" data-count>16</span></h2>
- <p class="sm-section-desc">Sign-in, dashboard, billing.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.sign_in_dashboard_billing">Sign-in, dashboard, billing.</p>
</header>
<ul class="sm-list">
<li>
@@ -3054,7 +3054,7 @@
<section class="sm-section" id="learn">
<header>
<h2><span data-i18n="sitemap_index.section_learn">Learn</span><span class="sm-count" data-count>532</span></h2>
- <p class="sm-section-desc">Docs, tutorials, and reference.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.docs_tutorials_and_reference">Docs, tutorials, and reference.</p>
</header>
<ul class="sm-list">
<li>
@@ -6787,7 +6787,7 @@
<section class="sm-section" id="blog">
<header>
<h2><span data-i18n="sitemap_index.section_blog">Blog</span><span class="sm-count" data-count>39</span></h2>
- <p class="sm-section-desc">Long-form announcements, launches, and writing from three.ws.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.long_form_announcements_launches_and_writing">Long-form announcements, launches, and writing from three.ws.</p>
</header>
<ul class="sm-list">
<li>
@@ -7141,7 +7141,7 @@
<section class="sm-section" id="machine">
<header>
<h2><span data-i18n="sitemap_index.section_machine">Machine-readable</span><span class="sm-count" data-count>20</span></h2>
- <p class="sm-section-desc">Indexes and well-known files for crawlers and AI agents.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.indexes_and_well_known_files_for_crawlers">Indexes and well-known files for crawlers and AI agents.</p>
</header>
<ul class="sm-list">
<li>
@@ -7290,7 +7290,7 @@
<section class="sm-section" id="news">
<header>
<h2><span data-i18n="sitemap_index.section_news">News</span><span class="sm-count" data-count>112</span></h2>
- <p class="sm-section-desc">Product launches, integrations, and announcements from three.ws.</p>
+ <p class="sm-section-desc" data-i18n="sitemap_index.product_launches_integrations_and_announceme">Product launches, integrations, and announcements from three.ws.</p>
</header>
<ul class="sm-list">
<li>
@@ -8081,10 +8081,10 @@
</section>
<div class="sm-empty" id="sm-empty" hidden>
<p><span data-i18n="sitemap_index.no_pages_match">No pages match</span> &ldquo;<span id="sm-empty-q"></span>&rdquo;.</p>
- <p class="sm-empty-hint">Try a shorter word, or search everything: global search covers agents, coins, and skills too.</p>
+ <p class="sm-empty-hint" data-i18n="sitemap_index.try_a_shorter_word_or_search_everything">Try a shorter word, or search everything: global search covers agents, coins, and skills too.</p>
<div class="sm-empty-actions">
- <button type="button" id="sm-empty-clear">Clear filter</button>
- <a id="sm-empty-search" href="/search">Search all of three.ws</a>
+ <button type="button" id="sm-empty-clear" data-i18n="sitemap_index.clear_filter">Clear filter</button>
+ <a id="sm-empty-search" href="/search" data-i18n="sitemap_index.search_all_of_three_ws">Search all of three.ws</a>
</div>
</div>
</main>
diff --git a/tests/actions-agent-tip-and-buy.test.js b/tests/actions-agent-tip-and-buy.test.js
new file mode 100644
index 000000000..6bdf8bc90
--- /dev/null
+++ b/tests/actions-agent-tip-and-buy.test.js
@@ -0,0 +1,303 @@
+// Coverage for the "Tip this agent" and "Buy this agent's coin" Solana Blinks:
+//
+// api/actions/agent-tip.js unsigned SOL/$THREE transfer to the agent's own wallet
+// api/actions/agent-buy-coin.js unsigned Jupiter swap into the agent's pump.fun mint
+//
+// Both wrap the same unsigned-transaction builders (buildTransferTransaction,
+// buildSwapTransaction) and envelope/header pattern as api/actions/avatar.js.
+// The cases below pin the behaviour a Blink client depends on:
+//
+// 1. The GET card carries the Action spec's `type` and version headers.
+// 2. `?agent=` only ever names a real agent id; a non-uuid is 400.
+// 3. An unknown agent is 404; an agent with no mainnet launch is 404 for buy-coin.
+// 4. POST rejects an off-curve (PDA) account before calling any builder.
+// 5. POST with a valid account/amount calls the expected builder with the
+// expected arguments and returns the serialized transaction.
+// 6. The tip endpoint's `token=THREE` branch passes the hardcoded $THREE
+// mint to the builder, never an arbitrary caller-supplied mint.
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const sqlMock = vi.fn();
+vi.mock('../api/_lib/db.js', () => ({ sql: (...a) => sqlMock(...a) }));
+
+const getOrCreateAgentSolanaWallet = vi.fn();
+vi.mock('../api/_lib/agent-wallet.js', () => ({
+ getOrCreateAgentSolanaWallet: (...a) => getOrCreateAgentSolanaWallet(...a),
+}));
+
+vi.mock('../api/_lib/solana/connection.js', () => ({
+ solanaConnection: () => ({}),
+}));
+
+const buildTransferTransaction = vi.fn();
+const buildSwapTransaction = vi.fn();
+vi.mock('../api/_lib/custody/builders.js', async (importOriginal) => {
+ const actual = await importOriginal();
+ return {
+ ...actual,
+ buildTransferTransaction: (...a) => buildTransferTransaction(...a),
+ buildSwapTransaction: (...a) => buildSwapTransaction(...a),
+ };
+});
+
+const { default: tipHandler } = await import('../api/actions/agent-tip.js');
+const { default: buyCoinHandler } = await import('../api/actions/agent-buy-coin.js');
+
+// $THREE, the platform's own coin, doubles as a known-good on-curve pubkey.
+const ON_CURVE = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
+const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
+const MEMO_PROGRAM = 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr';
+const AGENT_UUID = '3f1c8a52-9f6b-4a3d-8c21-0d5b7e9a1c44';
+const AGENT_ROW = { id: AGENT_UUID, name: 'Nova', avatar_thumbnail_key: null };
+const COIN_ROW = { mint: 'coin-mint-placeholder-not-real', name: 'Nova Coin', symbol: 'NOVA' };
+
+function mockReq(method, url, body) {
+ const req = { method, url, headers: { host: 'localhost' } };
+ if (body !== undefined) {
+ req.headers['content-type'] = 'application/json';
+ req.body = body;
+ }
+ return req;
+}
+
+function mockRes() {
+ return {
+ statusCode: 200,
+ headers: {},
+ body: undefined,
+ ended: false,
+ setHeader(k, v) { this.headers[k.toLowerCase()] = v; },
+ getHeader(k) { return this.headers[k.toLowerCase()]; },
+ end(b) { this.body = b; this.ended = true; },
+ };
+}
+
+const parse = (res) => JSON.parse(String(res.body));
+
+// Both handlers query sql() sequentially (agent lookup first, coin lookup
+// second for buy-coin); this just replays canned rows in call order.
+function queueSql(...results) {
+ let i = 0;
+ sqlMock.mockImplementation(async () => results[i++] ?? []);
+}
+
+function fakeTransaction() {
+ return { serialize: () => Buffer.from('fake-serialized-tx') };
+}
+
+beforeEach(() => {
+ sqlMock.mockReset();
+ getOrCreateAgentSolanaWallet.mockReset();
+ buildTransferTransaction.mockReset();
+ buildSwapTransaction.mockReset();
+});
+
+describe('api/actions/agent-tip GET (the Blink card)', () => {
+ it('returns a spec-shaped action with version headers', async () => {
+ queueSql([AGENT_ROW]);
+ const res = mockRes();
+ await tipHandler(mockReq('GET', `/api/actions/agent-tip?agent=${AGENT_UUID}`), res);
+
+ expect(res.statusCode).toBe(200);
+ const card = parse(res);
+ expect(card.type).toBe('action');
+ expect(card.title).toBe('Tip Nova');
+ expect(card.links.actions.length).toBeGreaterThan(1);
+ expect(card.links.actions.at(-1).parameters[0]).toMatchObject({ name: 'amount' });
+ expect(res.headers['x-action-version']).toBe('2.1.3');
+ expect(res.headers['x-blockchain-ids']).toMatch(/^solana:/);
+ });
+
+ it('rejects a non-uuid agent id as 400', async () => {
+ const res = mockRes();
+ await tipHandler(mockReq('GET', '/api/actions/agent-tip?agent=not-a-uuid'), res);
+
+ expect(res.statusCode).toBe(400);
+ expect(parse(res).error).toBe('bad_request');
+ expect(sqlMock).not.toHaveBeenCalled();
+ });
+
+ it('404s an unknown agent', async () => {
+ queueSql([]);
+ const res = mockRes();
+ await tipHandler(mockReq('GET', `/api/actions/agent-tip?agent=${AGENT_UUID}`), res);
+
+ expect(res.statusCode).toBe(404);
+ expect(parse(res).message).toMatch(/not available/i);
+ });
+
+ it('puts the Action version headers on the OPTIONS preflight', async () => {
+ const res = mockRes();
+ await tipHandler(mockReq('OPTIONS', '/api/actions/agent-tip'), res);
+
+ expect(res.statusCode).toBe(204);
+ expect(res.headers['x-action-version']).toBe('2.1.3');
+ });
+});
+
+describe('api/actions/agent-tip POST (the tip transaction)', () => {
+ it('rejects an off-curve account before calling any builder', async () => {
+ queueSql([AGENT_ROW]);
+ const { PublicKey } = await import('@solana/web3.js');
+ const [pda] = PublicKey.findProgramAddressSync([Buffer.from('three')], new PublicKey(MEMO_PROGRAM));
+
+ const res = mockRes();
+ await tipHandler(
+ mockReq('POST', `/api/actions/agent-tip?agent=${AGENT_UUID}`, { account: pda.toBase58(), amount: 0.1 }),
+ res,
+ );
+
+ expect(res.statusCode).toBe(400);
+ expect(buildTransferTransaction).not.toHaveBeenCalled();
+ expect(getOrCreateAgentSolanaWallet).not.toHaveBeenCalled();
+ });
+
+ it('builds a SOL transfer to the agent own wallet for a valid account/amount', async () => {
+ queueSql([AGENT_ROW]);
+ getOrCreateAgentSolanaWallet.mockResolvedValue({ address: 'agent-wallet-address', created: false });
+ buildTransferTransaction.mockResolvedValue({ transaction: fakeTransaction() });
+
+ const res = mockRes();
+ await tipHandler(
+ mockReq('POST', `/api/actions/agent-tip?agent=${AGENT_UUID}`, { account: ON_CURVE, amount: 0.25 }),
+ res,
+ );
+
+ expect(res.statusCode).toBe(200);
+ expect(parse(res).type).toBe('transaction');
+ expect(buildTransferTransaction).toHaveBeenCalledWith(
+ expect.objectContaining({
+ sender: ON_CURVE,
+ recipient: 'agent-wallet-address',
+ amount: 0.25,
+ token: 'SOL',
+ memo: `tip:${AGENT_UUID}`,
+ network: 'mainnet',
+ }),
+ );
+ });
+
+ it('passes the hardcoded $THREE mint, not a caller-supplied one, for token=THREE', async () => {
+ queueSql([AGENT_ROW]);
+ getOrCreateAgentSolanaWallet.mockResolvedValue({ address: 'agent-wallet-address', created: false });
+ buildTransferTransaction.mockResolvedValue({ transaction: fakeTransaction() });
+
+ const res = mockRes();
+ await tipHandler(
+ mockReq('POST', `/api/actions/agent-tip?agent=${AGENT_UUID}&token=THREE`, { account: ON_CURVE, amount: 10 }),
+ res,
+ );
+
+ expect(res.statusCode).toBe(200);
+ expect(buildTransferTransaction).toHaveBeenCalledWith(
+ expect.objectContaining({ token: THREE_MINT }),
+ );
+ });
+
+ it('rejects a non-positive amount before resolving the wallet', async () => {
+ queueSql([AGENT_ROW]);
+ const res = mockRes();
+ await tipHandler(
+ mockReq('POST', `/api/actions/agent-tip?agent=${AGENT_UUID}`, { account: ON_CURVE, amount: 0 }),
+ res,
+ );
+
+ expect(res.statusCode).toBe(400);
+ expect(getOrCreateAgentSolanaWallet).not.toHaveBeenCalled();
+ });
+});
+
+describe('api/actions/agent-buy-coin GET (the Blink card)', () => {
+ it('returns a spec-shaped action naming the agent coin', async () => {
+ queueSql([AGENT_ROW], [COIN_ROW]);
+ const res = mockRes();
+ await buyCoinHandler(mockReq('GET', `/api/actions/agent-buy-coin?agent=${AGENT_UUID}`), res);
+
+ expect(res.statusCode).toBe(200);
+ const card = parse(res);
+ expect(card.type).toBe('action');
+ expect(card.title).toBe('Buy NOVA');
+ expect(res.headers['x-action-version']).toBe('2.1.3');
+ });
+
+ it('rejects a non-uuid agent id as 400', async () => {
+ const res = mockRes();
+ await buyCoinHandler(mockReq('GET', '/api/actions/agent-buy-coin?agent=not-a-uuid'), res);
+
+ expect(res.statusCode).toBe(400);
+ expect(sqlMock).not.toHaveBeenCalled();
+ });
+
+ it('404s an unknown agent', async () => {
+ queueSql([]);
+ const res = mockRes();
+ await buyCoinHandler(mockReq('GET', `/api/actions/agent-buy-coin?agent=${AGENT_UUID}`), res);
+
+ expect(res.statusCode).toBe(404);
+ expect(parse(res).message).toMatch(/not available/i);
+ });
+
+ it('404s an agent with no mainnet launch instead of a card with nothing to buy', async () => {
+ queueSql([AGENT_ROW], []);
+ const res = mockRes();
+ await buyCoinHandler(mockReq('GET', `/api/actions/agent-buy-coin?agent=${AGENT_UUID}`), res);
+
+ expect(res.statusCode).toBe(404);
+ expect(parse(res).message).toMatch(/not launched a coin/i);
+ });
+});
+
+describe('api/actions/agent-buy-coin POST (the swap transaction)', () => {
+ it('rejects an off-curve account before calling any builder', async () => {
+ queueSql([AGENT_ROW], [COIN_ROW]);
+ const { PublicKey } = await import('@solana/web3.js');
+ const [pda] = PublicKey.findProgramAddressSync([Buffer.from('three')], new PublicKey(MEMO_PROGRAM));
+
+ const res = mockRes();
+ await buyCoinHandler(
+ mockReq('POST', `/api/actions/agent-buy-coin?agent=${AGENT_UUID}`, { account: pda.toBase58(), amount: 0.5 }),
+ res,
+ );
+
+ expect(res.statusCode).toBe(400);
+ expect(buildSwapTransaction).not.toHaveBeenCalled();
+ });
+
+ it('builds a SOL -> mint swap for a valid account/amount', async () => {
+ queueSql([AGENT_ROW], [COIN_ROW]);
+ buildSwapTransaction.mockResolvedValue({ transaction: fakeTransaction() });
+
+ const res = mockRes();
+ await buyCoinHandler(
+ mockReq('POST', `/api/actions/agent-buy-coin?agent=${AGENT_UUID}`, { account: ON_CURVE, amount: 0.5 }),
+ res,
+ );
+
+ expect(res.statusCode).toBe(200);
+ expect(parse(res).type).toBe('transaction');
+ expect(buildSwapTransaction).toHaveBeenCalledWith(
+ expect.objectContaining({
+ sender: ON_CURVE,
+ inputMint: 'So11111111111111111111111111111111111111112',
+ outputMint: COIN_ROW.mint,
+ amount: 0.5,
+ slippageBps: 50,
+ }),
+ );
+ });
+
+ it('surfaces a no_route builder error as the 422 it already is, not a 500', async () => {
+ queueSql([AGENT_ROW], [COIN_ROW]);
+ buildSwapTransaction.mockRejectedValue(Object.assign(new Error('No swap route found for this pair and amount'), { status: 422, code: 'no_route' }));
+
+ const res = mockRes();
+ await buyCoinHandler(
+ mockReq('POST', `/api/actions/agent-buy-coin?agent=${AGENT_UUID}`, { account: ON_CURVE, amount: 0.5 }),
+ res,
+ );
+
+ expect(res.statusCode).toBe(422);
+ expect(parse(res).error).toBe('no_route');
+ });
+});