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.

10.3 KB
Raw Blame
// POST /api/forever/inscribe
//
// Creates a real Bitcoin text inscription via OrdinalsBot. The message is
// embedded into a Taproot witness on Bitcoin mainnet, where it lives forever.
//
// Body: { message: string, receiveAddress?: string, feeRate?: number }
//   - message: 1 to 1500 chars of UTF-8 text to inscribe
//   - receiveAddress: optional Taproot (bc1p...) address that receives the
//     inscription. If omitted, falls back to the platform vault address
//     (env.BTC_INSCRIPTION_RECEIVE_ADDRESS).
//   - feeRate: optional sats/vB. Defaults to 8 (medium). Range 1 to 200.
//
// Response 200:
//   { orderId, charge: { address, amount, currency, lightning_invoice? },
//     receiveAddress, feeRate, sizeBytes, mempoolUrl, ordinalsUrl?, status }
//
// Errors:
//   400: invalid body / message / address / fee rate
//   401: not signed in and no valid bearer token
//   429: per-IP ceiling, or OrdinalsBot throttling the platform key
//   502: OrdinalsBot upstream error
//   503: receive address not provided and none configured

import { bech32m } from '@scure/base';
import { cors, error, json, readJson, rateLimited } from '../_lib/http.js';
import { getSessionUser, authenticateBearer, extractBearer } from '../_lib/auth.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { fetchUpstream } from '../_lib/upstream-fetch.js';

const ORDINALSBOT_BASE_URL =
	process.env.ORDINALSBOT_BASE_URL || 'https://api.ordinalsbot.com';

const MAX_MESSAGE_BYTES = 1500;
const MIN_FEE_RATE = 1;
const MAX_FEE_RATE = 200;
const DEFAULT_FEE_RATE = 8;

// Bitcoin Taproot (P2TR / bc1p...) is the only address class OrdinalsBot will
// send inscriptions to. Mainnet HRP "bc", witness version 1, bech32m, 62 chars.
const TAPROOT_RE = /^bc1p[02-9ac-hj-np-z]{58}$/;

// A P2TR address encodes the witness version plus a 32-byte program, which is
// 1 + ceil(256 / 5) = 53 bech32 words.
const TAPROOT_WORD_COUNT = 53;

/**
 * Full bech32m validation, not just the character shape. A single mistyped
 * character keeps the bc1p... shape and only the checksum catches it, and
 * OrdinalsBot answers a bad address with an opaque proxy error that tells the
 * user nothing. Verifying here turns that into a precise 400 and spares the
 * upstream order-create call entirely.
 */
function hasValidTaprootChecksum(address) {
	try {
		const decoded = bech32m.decode(address, 90);
		return (
			decoded.prefix === 'bc' &&
			decoded.words[0] === 1 &&
			decoded.words.length === TAPROOT_WORD_COUNT
		);
	} catch {
		return false;
	}
}

/** OrdinalsBot reports failures as a string or an array of strings. */
function upstreamMessage(data) {
	const raw = data?.message ?? data?.error;
	if (Array.isArray(raw)) return raw.filter(Boolean).map(String).join('; ');
	if (typeof raw === 'string') return raw;
	return '';
}

function validateMessage(raw) {
	if (typeof raw !== 'string') {
		return { error: 'message must be a string' };
	}
	const message = raw.trim();
	if (message.length === 0) {
		return { error: 'message cannot be empty' };
	}
	const bytes = Buffer.byteLength(message, 'utf8');
	if (bytes > MAX_MESSAGE_BYTES) {
		return {
			error: `message too long: ${bytes} bytes (max ${MAX_MESSAGE_BYTES})`,
		};
	}
	return { message, bytes };
}

function validateAddress(raw) {
	if (raw === undefined || raw === null || raw === '') return { address: null };
	if (typeof raw !== 'string') return { error: 'receiveAddress must be a string' };
	const address = raw.trim();
	if (address === '') return { address: null };
	if (!TAPROOT_RE.test(address)) {
		return {
			error:
				'receiveAddress must be a Bitcoin Taproot address (bc1p...). Ordinals can only be received by Taproot wallets.',
		};
	}
	if (!hasValidTaprootChecksum(address)) {
		return {
			error:
				'receiveAddress failed its bech32m checksum, so it is not a real Taproot address. Copy the bc1p... address again from your wallet.',
		};
	}
	return { address };
}

function validateFeeRate(raw) {
	if (raw === undefined || raw === null || raw === '') {
		return { feeRate: DEFAULT_FEE_RATE };
	}
	const n = Number(raw);
	if (!Number.isFinite(n) || !Number.isInteger(n)) {
		return { error: 'feeRate must be an integer' };
	}
	if (n < MIN_FEE_RATE || n > MAX_FEE_RATE) {
		return { error: `feeRate must be between ${MIN_FEE_RATE} and ${MAX_FEE_RATE} sats/vB` };
	}
	return { feeRate: n };
}

function buildTextDataURL(message) {
	const base64 = Buffer.from(message, 'utf8').toString('base64');
	return `data:text/plain;charset=utf-8;base64,${base64}`;
}

async function createOrdinalsBotOrder({ message, receiveAddress, feeRate }) {
	const sizeBytes = Buffer.byteLength(message, 'utf8');
	const body = {
		files: [
			{
				name: 'forever.txt',
				size: sizeBytes,
				type: 'text/plain;charset=utf-8',
				dataURL: buildTextDataURL(message),
			},
		],
		receiveAddress,
		fee: feeRate,
		lowPostage: true,
	};
	const headers = { 'content-type': 'application/json' };
	if (process.env.ORDINALSBOT_API_KEY) {
		headers['x-api-key'] = process.env.ORDINALSBOT_API_KEY;
	}
	// Placing an order is a paid, non-idempotent action: bound it with a deadline
	// but never retry it, because a retry after a request that actually landed
	// would buy a second inscription. Every status is returned untouched so the
	// existing non-JSON and error-status handling below is unchanged.
	const res = await fetchUpstream(`${ORDINALSBOT_BASE_URL}/order`, {
		method: 'POST',
		headers,
		body: JSON.stringify(body),
	}, { timeoutMs: 30_000, attempts: 1, okWhen: () => true, label: 'ordinalsbot-order' });
	const text = await res.text();
	let data;
	try {
		data = JSON.parse(text);
	} catch {
		const err = new Error(`OrdinalsBot returned non-JSON (${res.status})`);
		err.status = 502;
		err.upstream = text.slice(0, 300);
		throw err;
	}
	// OrdinalsBot signals failure two different ways: a non-2xx status, and a
	// 200 carrying {status:"error"}. Neither status is usable as our own. It
	// answers a rejected payload with a bare 404 and echoes its own internal
	// axios text, and a key or quota fault would arrive as 401/403. Passing any
	// of those through would tell the caller their request was not found or that
	// THEY are unauthorized, and the 200 case would ship an error envelope under
	// a success status that the client reads as a created order. Every upstream
	// fault is our gateway's fault: 502, except a throttle we can honestly relay.
	if (!res.ok || data.status === 'error') {
		const detail = upstreamMessage(data);
		const err = new Error(
			detail
				? `OrdinalsBot rejected the inscription order: ${detail}`
				: `OrdinalsBot returned ${res.status}`,
		);
		err.status = res.status === 429 ? 429 : 502;
		err.upstream = detail || null;
		throw err;
	}
	return data;
}

function shapeChargeResponse(order, { receiveAddress, feeRate, sizeBytes }) {
	const charge = order.charge || {};
	const address = charge.address || order.payAddress;
	const amount = Number(charge.amount ?? order.fileCost ?? 0);
	const lightning = charge.lightning_invoice || charge.lightningInvoice || null;
	const status = order.status || charge.status || 'pending';

	return {
		orderId: order.id || order.orderId,
		status,
		charge: {
			address,
			amount,
			amountBtc: amount ? amount / 1e8 : null,
			currency: 'BTC',
			lightningInvoice:
				typeof lightning === 'object' && lightning ? lightning.payreq || null : lightning,
			expiresAt: charge.expires_at || charge.expiresAt || null,
		},
		receiveAddress,
		feeRate,
		sizeBytes,
		mempoolBaseUrl: 'https://mempool.space',
		ordinalsViewerBaseUrl: 'https://ordinals.com/inscription',
	};
}

export default async function handler(req, res) {
	if (cors(req, res, { origins: '*', methods: 'POST,OPTIONS' })) return;
	if (req.method !== 'POST') return error(res, 405, 'method_not_allowed', 'POST only');

	// Creating an OrdinalsBot order spends the platform's API key/quota. Require a
	// signed-in user or a valid bearer token, and rate-limit per IP, so the endpoint
	// can't be scripted anonymously to spam third-party order creation.
	const session = await getSessionUser(req).catch(() => null);
	let authed = !!session;
	if (!authed) {
		const bearer = extractBearer(req);
		if (bearer) authed = !!(await authenticateBearer(bearer).catch(() => null));
	}
	if (!authed) return error(res, 401, 'unauthorized', 'sign in or provide a valid bearer token');

	const rl = await limits.inscribeIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	let body;
	try {
		body = await readJson(req);
	} catch (e) {
		return error(res, e.status || 400, 'bad_request', e.message || 'invalid request body');
	}
	if (!body || typeof body !== 'object' || Array.isArray(body)) {
		return error(res, 400, 'bad_request', 'request body must be a JSON object');
	}

	const msg = validateMessage(body.message);
	if (msg.error) return error(res, 400, 'invalid_message', msg.error);

	const addr = validateAddress(body.receiveAddress);
	if (addr.error) return error(res, 400, 'invalid_receive_address', addr.error);

	const fee = validateFeeRate(body.feeRate);
	if (fee.error) return error(res, 400, 'invalid_fee_rate', fee.error);

	const vaultAddress = (process.env.BTC_INSCRIPTION_RECEIVE_ADDRESS || '').trim();
	const receiveAddress = addr.address || vaultAddress || null;
	if (!receiveAddress) {
		return error(
			res,
			503,
			'no_receive_address',
			'No Taproot receive address provided and BTC_INSCRIPTION_RECEIVE_ADDRESS is not configured. Send your bc1p... address in the request body.',
		);
	}
	// The vault address comes from config, so it skipped the request validation
	// above. A typo there would mint inscriptions into an unspendable address,
	// so hold it to the same bar and fail loudly instead of silently upstream.
	if (!addr.address && !(TAPROOT_RE.test(receiveAddress) && hasValidTaprootChecksum(receiveAddress))) {
		return error(
			res,
			503,
			'invalid_vault_address',
			'BTC_INSCRIPTION_RECEIVE_ADDRESS is not a valid Bitcoin Taproot address. Send your own bc1p... address in the request body.',
		);
	}

	let order;
	try {
		order = await createOrdinalsBotOrder({
			message: msg.message,
			receiveAddress,
			feeRate: fee.feeRate,
		});
	} catch (e) {
		const status = e.status === 429 ? 429 : 502;
		return error(
			res,
			status,
			status === 429 ? 'upstream_rate_limited' : 'inscription_failed',
			e.message,
			e.upstream ? { upstream: e.upstream } : {},
		);
	}

	const shaped = shapeChargeResponse(order, {
		receiveAddress,
		feeRate: fee.feeRate,
		sizeBytes: msg.bytes,
	});

	return json(res, 200, shaped);
}