@agi-cli/sdk 0.1.131 → 0.1.133

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agi-cli/sdk",
-	"version": "0.1.131",
+	"version": "0.1.133",
 	"description": "AI agent SDK for building intelligent assistants - tree-shakable and comprehensive",
 	"author": "ntishxyz",
 	"license": "MIT",

package/src/core/src/providers/resolver.ts

@@ -10,6 +10,23 @@ import {
 } from '../../../providers/src/index.ts';
 import type { OAuth } from '../../../types/src/index.ts';
 
+function needsResponsesApi(model: string): boolean {
+	const m = model.toLowerCase();
+	if (m.includes('gpt-5')) return true;
+	if (m.startsWith('o1')) return true;
+	if (m.startsWith('o3')) return true;
+	if (m.startsWith('o4')) return true;
+	if (m.includes('codex-mini')) return true;
+	return false;
+}
+
+function resolveOpenAIModel(
+	instance: ReturnType<typeof createOpenAI>,
+	model: string,
+) {
+	return needsResponsesApi(model) ? instance.responses(model) : instance(model);
+}
+
 export type ProviderName =
 	| 'openai'
 	| 'anthropic'
@@ -45,13 +62,13 @@ export async function resolveModel(
 				apiKey: config.apiKey || 'oauth-token',
 				fetch: config.customFetch,
 			});
-			return instance(model);
+			return resolveOpenAIModel(instance, model);
 		}
 		if (config.apiKey) {
 			const instance = createOpenAI({ apiKey: config.apiKey });
-			return instance(model);
+			return resolveOpenAIModel(instance, model);
 		}
-		return openai(model);
+		return needsResponsesApi(model) ? openai.responses(model) : openai(model);
 	}
 
 	if (provider === 'anthropic') {
@@ -143,14 +160,12 @@ export async function resolveModel(
 		}
 		const baseURL = config.baseURL || process.env.SOLFORGE_BASE_URL;
 		const rpcURL = process.env.SOLFORGE_SOLANA_RPC_URL;
-		const topupAmount = process.env.SOLFORGE_TOPUP_MICRO_USDC;
 		return createSolforgeModel(
 			model,
 			{ privateKey },
 			{
 				baseURL,
 				rpcURL,
-				topupAmountMicroUsdc: topupAmount,
 			},
 		);
 	}

package/src/index.ts

@@ -57,10 +57,15 @@ export {
 export {
 	createSolforgeFetch,
 	createSolforgeModel,
+	fetchSolforgeBalance,
+	getPublicKeyFromPrivate,
+	fetchSolanaUsdcBalance,
 } from './providers/src/index.ts';
 export type {
 	SolforgeAuth,
 	SolforgeProviderOptions,
+	SolforgeBalanceResponse,
+	SolanaUsdcBalanceResponse,
 } from './providers/src/index.ts';
 export {
 	createOpenAIOAuthFetch,

package/src/providers/src/catalog-manual.ts

@@ -7,6 +7,20 @@ import type {
 type CatalogMap = Partial<Record<ProviderId, ProviderCatalogEntry>>;
 
 const SOLFORGE_ID: ProviderId = 'solforge';
+
+const isAllowedOpenAIModel = (id: string): boolean => {
+	if (id === 'codex-mini-latest') return true;
+	if (id.startsWith('gpt-5')) return true;
+	if (id.includes('codex')) return true;
+	return false;
+};
+
+const isAllowedAnthropicModel = (id: string): boolean => {
+	if (id.includes('-4-') || id.includes('-4.')) return true;
+	if (id.match(/claude-(haiku|sonnet|opus)-4/)) return true;
+	return false;
+};
+
 const SOLFORGE_SOURCES: Array<{ id: ProviderId; npm: string }> = [
 	{
 		id: 'openai',
@@ -39,7 +53,12 @@ function cloneModel(model: ModelInfo): ModelInfo {
 
 function buildSolforgeEntry(base: CatalogMap): ProviderCatalogEntry | null {
 	const solforgeModels = SOLFORGE_SOURCES.flatMap(({ id, npm }) => {
-		const sourceModels = base[id]?.models ?? [];
+		const allModels = base[id]?.models ?? [];
+		const sourceModels = allModels.filter((model) => {
+			if (id === 'openai') return isAllowedOpenAIModel(model.id);
+			if (id === 'anthropic') return isAllowedAnthropicModel(model.id);
+			return true;
+		});
 		return sourceModels.map((model) => {
 			const cloned = cloneModel(model);
 			cloned.provider = { ...(cloned.provider ?? {}), npm };
@@ -61,7 +80,7 @@ function buildSolforgeEntry(base: CatalogMap): ProviderCatalogEntry | null {
 		return providerA.localeCompare(providerB);
 	});
 
-	const defaultModelId = 'gpt-4o-mini';
+	const defaultModelId = 'codex-mini-latest';
 	const defaultIdx = solforgeModels.findIndex((m) => m.id === defaultModelId);
 	if (defaultIdx > 0) {
 		const [picked] = solforgeModels.splice(defaultIdx, 1);

package/src/providers/src/catalog.ts

@@ -324,7 +324,7 @@ export const catalog: Partial<Record<ProviderId, ProviderCatalogEntry>> = {
 				cost: {
 					input: 1.25,
 					output: 10,
-					cacheRead: 0.13,
+					cacheRead: 0.125,
 				},
 				limit: {
 					context: 400000,
@@ -398,7 +398,7 @@ export const catalog: Partial<Record<ProviderId, ProviderCatalogEntry>> = {
 				cost: {
 					input: 0.25,
 					output: 2,
-					cacheRead: 0.03,
+					cacheRead: 0.025,
 				},
 				limit: {
 					context: 400000,
@@ -423,7 +423,7 @@ export const catalog: Partial<Record<ProviderId, ProviderCatalogEntry>> = {
 				cost: {
 					input: 0.05,
 					output: 0.4,
-					cacheRead: 0.01,
+					cacheRead: 0.005,
 				},
 				limit: {
 					context: 400000,
@@ -633,7 +633,7 @@ export const catalog: Partial<Record<ProviderId, ProviderCatalogEntry>> = {
 				id: 'gpt-5.2-codex',
 				label: 'GPT-5.2 Codex',
 				modalities: {
-					input: ['text', 'image'],
+					input: ['text', 'image', 'pdf'],
 					output: ['text'],
 				},
 				toolCall: true,
@@ -4278,6 +4278,31 @@ export const catalog: Partial<Record<ProviderId, ProviderCatalogEntry>> = {
 					output: 128000,
 				},
 			},
+			{
+				id: 'openai/gpt-5.1-codex-max',
+				label: 'GPT-5.1-Codex-Max',
+				modalities: {
+					input: ['text', 'image'],
+					output: ['text'],
+				},
+				toolCall: true,
+				reasoning: true,
+				attachment: true,
+				temperature: true,
+				knowledge: '2024-09-30',
+				releaseDate: '2025-11-13',
+				lastUpdated: '2025-11-13',
+				openWeights: false,
+				cost: {
+					input: 1.1,
+					output: 9,
+					cacheRead: 0.11,
+				},
+				limit: {
+					context: 400000,
+					output: 128000,
+				},
+			},
 			{
 				id: 'openai/gpt-5.1-codex-mini',
 				label: 'GPT-5.1-Codex-Mini',
@@ -5925,6 +5950,31 @@ export const catalog: Partial<Record<ProviderId, ProviderCatalogEntry>> = {
 					output: 131072,
 				},
 			},
+			{
+				id: 'glm-4.7',
+				label: 'GLM-4.7',
+				modalities: {
+					input: ['text'],
+					output: ['text'],
+				},
+				toolCall: true,
+				reasoning: true,
+				attachment: false,
+				temperature: true,
+				knowledge: '2025-04',
+				releaseDate: '2025-12-22',
+				lastUpdated: '2025-12-22',
+				openWeights: true,
+				cost: {
+					input: 0.6,
+					output: 2.2,
+					cacheRead: 0.1,
+				},
+				limit: {
+					context: 204800,
+					output: 131072,
+				},
+			},
 			{
 				id: 'glm-4.7-free',
 				label: 'GLM-4.7',
@@ -6178,7 +6228,7 @@ export const catalog: Partial<Record<ProviderId, ProviderCatalogEntry>> = {
 				id: 'gpt-5.2-codex',
 				label: 'GPT-5.2 Codex',
 				modalities: {
-					input: ['text', 'image'],
+					input: ['text', 'image', 'pdf'],
 					output: ['text'],
 				},
 				toolCall: true,
@@ -6694,6 +6744,31 @@ export const catalog: Partial<Record<ProviderId, ProviderCatalogEntry>> = {
 					output: 131072,
 				},
 			},
+			{
+				id: 'glm-4.7-flash',
+				label: 'GLM-4.7-Flash',
+				modalities: {
+					input: ['text'],
+					output: ['text'],
+				},
+				toolCall: true,
+				reasoning: true,
+				attachment: false,
+				temperature: true,
+				knowledge: '2025-04',
+				releaseDate: '2026-01-19',
+				lastUpdated: '2026-01-19',
+				openWeights: true,
+				cost: {
+					input: 0,
+					output: 0,
+					cacheRead: 0,
+				},
+				limit: {
+					context: 200000,
+					output: 131072,
+				},
+			},
 		],
 		label: 'Z.AI Coding Plan',
 		env: ['ZHIPU_API_KEY'],

package/src/providers/src/index.ts

@@ -20,11 +20,16 @@ export { providerEnvVar, readEnvKey, setEnvKey } from './env.ts';
 export {
 	createSolforgeFetch,
 	createSolforgeModel,
+	fetchSolforgeBalance,
+	getPublicKeyFromPrivate,
+	fetchSolanaUsdcBalance,
 } from './solforge-client.ts';
 export type {
 	SolforgeAuth,
 	SolforgeProviderOptions,
 	SolforgePaymentCallbacks,
+	SolforgeBalanceResponse,
+	SolanaUsdcBalanceResponse,
 } from './solforge-client.ts';
 export {
 	createOpenAIOAuthFetch,

package/src/providers/src/openai-oauth-client.ts

@@ -14,6 +14,8 @@ export type OpenAIOAuthConfig = {
 	instructions?: string;
 	reasoningEffort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh';
 	reasoningSummary?: 'auto' | 'detailed';
+	promptCacheKey?: string;
+	promptCacheRetention?: 'in_memory' | '24h';
 };
 
 async function ensureValidToken(
@@ -44,10 +46,38 @@ async function ensureValidToken(
 
 function stripIdsFromInput(input: unknown): unknown {
 	if (Array.isArray(input)) {
-		return input
+		const filtered = input.filter((item) => {
+			if (item && typeof item === 'object' && 'type' in item) {
+				if (item.type === 'item_reference') return false;
+			}
+			return true;
+		});
+
+		const validCallIds = new Set<string>();
+		for (const item of filtered) {
+			if (
+				item &&
+				typeof item === 'object' &&
+				'type' in item &&
+				item.type === 'function_call' &&
+				'call_id' in item &&
+				typeof item.call_id === 'string'
+			) {
+				validCallIds.add(item.call_id);
+			}
+		}
+
+		return filtered
 			.filter((item) => {
-				if (item && typeof item === 'object' && 'type' in item) {
-					if (item.type === 'item_reference') return false;
+				if (
+					item &&
+					typeof item === 'object' &&
+					'type' in item &&
+					item.type === 'function_call_output' &&
+					'call_id' in item &&
+					typeof item.call_id === 'string'
+				) {
+					return validCallIds.has(item.call_id);
 				}
 				return true;
 			})
@@ -155,6 +185,19 @@ export function createOpenAIOAuthFetch(config: OpenAIOAuthConfig) {
 					}
 				}
 
+				const cacheKey =
+					parsed.providerOptions?.openai?.promptCacheKey ||
+					config.promptCacheKey;
+				const cacheRetention =
+					parsed.providerOptions?.openai?.promptCacheRetention ||
+					config.promptCacheRetention;
+				if (cacheKey) {
+					parsed.prompt_cache_key = cacheKey;
+				}
+				if (cacheRetention) {
+					parsed.prompt_cache_retention = cacheRetention;
+				}
+
 				delete parsed.max_output_tokens;
 				delete parsed.max_completion_tokens;
 

package/src/providers/src/solforge-client.ts

@@ -10,14 +10,17 @@ import { createAnthropic } from '@ai-sdk/anthropic';
 
 const DEFAULT_BASE_URL = 'https://router.solforge.sh';
 const DEFAULT_RPC_URL = 'https://api.mainnet-beta.solana.com';
-const DEFAULT_TOPUP_AMOUNT = '5000000'; // $5.00
 const DEFAULT_MAX_ATTEMPTS = 3;
 const DEFAULT_MAX_PAYMENT_ATTEMPTS = 20;
 
 export type SolforgePaymentCallbacks = {
 	onPaymentRequired?: (amountUsd: number) => void;
 	onPaymentSigning?: () => void;
-	onPaymentComplete?: (data: { amountUsd: number; newBalance: number }) => void;
+	onPaymentComplete?: (data: {
+		amountUsd: number;
+		newBalance: number;
+		transactionId?: string;
+	}) => void;
 	onPaymentError?: (error: string) => void;
 };
 
@@ -25,11 +28,12 @@ export type SolforgeProviderOptions = {
 	baseURL?: string;
 	rpcURL?: string;
 	network?: string;
-	topupAmountMicroUsdc?: string;
 	maxRequestAttempts?: number;
 	maxPaymentAttempts?: number;
 	callbacks?: SolforgePaymentCallbacks;
 	providerNpm?: string;
+	promptCacheKey?: string;
+	promptCacheRetention?: 'in_memory' | '24h';
 };
 
 export type SolforgeAuth = {
@@ -60,8 +64,45 @@ type PaymentResponse = {
 	new_balance?: number | string;
 	amount?: number;
 	balance?: number;
+	transaction?: string;
 };
 
+type PaymentQueueEntry = {
+	promise: Promise<void>;
+	resolve: () => void;
+};
+
+const paymentQueues = new Map<string, PaymentQueueEntry>();
+const globalPaymentAttempts = new Map<string, number>();
+
+async function acquirePaymentLock(walletAddress: string): Promise<() => void> {
+	const existing = paymentQueues.get(walletAddress);
+
+	let resolveFunc: () => void = () => {};
+	const newPromise = new Promise<void>((resolve) => {
+		resolveFunc = resolve;
+	});
+
+	const entry: PaymentQueueEntry = {
+		promise: newPromise,
+		resolve: resolveFunc,
+	};
+
+	paymentQueues.set(walletAddress, entry);
+
+	if (existing) {
+		console.log('[Solforge] Waiting for pending payment to complete...');
+		await existing.promise;
+	}
+
+	return () => {
+		if (paymentQueues.get(walletAddress) === entry) {
+			paymentQueues.delete(walletAddress);
+		}
+		resolveFunc();
+	};
+}
+
 export function createSolforgeFetch(
 	auth: SolforgeAuth,
 	options: SolforgeProviderOptions = {},
@@ -71,14 +112,14 @@ export function createSolforgeFetch(
 	const walletAddress = keypair.publicKey.toBase58();
 	const baseURL = trimTrailingSlash(options.baseURL ?? DEFAULT_BASE_URL);
 	const rpcURL = options.rpcURL ?? DEFAULT_RPC_URL;
-	const targetTopup = options.topupAmountMicroUsdc ?? DEFAULT_TOPUP_AMOUNT;
 	const maxAttempts = options.maxRequestAttempts ?? DEFAULT_MAX_ATTEMPTS;
 	const maxPaymentAttempts =
 		options.maxPaymentAttempts ?? DEFAULT_MAX_PAYMENT_ATTEMPTS;
 	const callbacks = options.callbacks ?? {};
+	const promptCacheKey = options.promptCacheKey;
+	const promptCacheRetention = options.promptCacheRetention;
 
 	const baseFetch = globalThis.fetch.bind(globalThis);
-	let paymentAttempts = 0;
 
 	const buildWalletHeaders = () => {
 		const nonce = Date.now().toString();
@@ -98,19 +139,112 @@ export function createSolforgeFetch(
 
 		while (attempt < maxAttempts) {
 			attempt++;
+			let body = init?.body;
+			if (body && typeof body === 'string') {
+				try {
+					const parsed = JSON.parse(body);
+
+					if (promptCacheKey) parsed.prompt_cache_key = promptCacheKey;
+					if (promptCacheRetention)
+						parsed.prompt_cache_retention = promptCacheRetention;
+
+					const MAX_SYSTEM_CACHE = 1;
+					const MAX_MESSAGE_CACHE = 1;
+					let systemCacheUsed = 0;
+					let messageCacheUsed = 0;
+
+					if (parsed.system && Array.isArray(parsed.system)) {
+						parsed.system = parsed.system.map(
+							(
+								block: { type: string; cache_control?: unknown },
+								index: number,
+							) => {
+								if (block.cache_control) return block;
+								if (
+									systemCacheUsed < MAX_SYSTEM_CACHE &&
+									index === 0 &&
+									block.type === 'text'
+								) {
+									systemCacheUsed++;
+									return { ...block, cache_control: { type: 'ephemeral' } };
+								}
+								return block;
+							},
+						);
+					}
+
+					if (parsed.messages && Array.isArray(parsed.messages)) {
+						const messageCount = parsed.messages.length;
+						parsed.messages = parsed.messages.map(
+							(
+								msg: {
+									role: string;
+									content: unknown;
+									[key: string]: unknown;
+								},
+								msgIndex: number,
+							) => {
+								const isLast = msgIndex === messageCount - 1;
+
+								if (Array.isArray(msg.content)) {
+									const blocks = msg.content as {
+										type: string;
+										cache_control?: unknown;
+									}[];
+									const content = blocks.map((block, blockIndex) => {
+										if (block.cache_control) return block;
+										if (
+											isLast &&
+											messageCacheUsed < MAX_MESSAGE_CACHE &&
+											blockIndex === blocks.length - 1
+										) {
+											messageCacheUsed++;
+											return { ...block, cache_control: { type: 'ephemeral' } };
+										}
+										return block;
+									});
+									return { ...msg, content };
+								}
+
+								if (
+									isLast &&
+									messageCacheUsed < MAX_MESSAGE_CACHE &&
+									typeof msg.content === 'string'
+								) {
+									messageCacheUsed++;
+									return {
+										...msg,
+										content: [
+											{
+												type: 'text',
+												text: msg.content,
+												cache_control: { type: 'ephemeral' },
+											},
+										],
+									};
+								}
+
+								return msg;
+							},
+						);
+					}
+
+					body = JSON.stringify(parsed);
+				} catch {}
+			}
 			const headers = new Headers(init?.headers);
 			const walletHeaders = buildWalletHeaders();
 			headers.set('x-wallet-address', walletHeaders['x-wallet-address']);
 			headers.set('x-wallet-nonce', walletHeaders['x-wallet-nonce']);
 			headers.set('x-wallet-signature', walletHeaders['x-wallet-signature']);
-			const response = await baseFetch(input, { ...init, headers });
+			const response = await baseFetch(input, { ...init, body, headers });
 
 			if (response.status !== 402) {
 				return response;
 			}
 
 			const payload = await response.json().catch(() => ({}));
-			const requirement = pickPaymentRequirement(payload, targetTopup);
+			const requirement = pickPaymentRequirement(payload);
 			if (!requirement) {
 				callbacks.onPaymentError?.('Unsupported payment requirement');
 				throw new Error('Solforge: unsupported payment requirement');
@@ -120,7 +254,8 @@ export function createSolforgeFetch(
 				throw new Error('Solforge: payment failed after multiple attempts');
 			}
 
-			const remainingPayments = maxPaymentAttempts - paymentAttempts;
+			const currentAttempts = globalPaymentAttempts.get(walletAddress) ?? 0;
+			const remainingPayments = maxPaymentAttempts - currentAttempts;
 			if (remainingPayments <= 0) {
 				callbacks.onPaymentError?.('Maximum payment attempts exceeded');
 				throw new Error(
@@ -128,20 +263,29 @@ export function createSolforgeFetch(
 				);
 			}
 
-			const amountUsd = parseInt(requirement.maxAmountRequired, 10) / 1_000_000;
-			callbacks.onPaymentRequired?.(amountUsd);
-
-			const outcome = await handlePayment({
-				requirement,
-				keypair,
-				rpcURL,
-				baseURL,
-				baseFetch,
-				buildWalletHeaders,
-				maxAttempts: remainingPayments,
-				callbacks,
-			});
-			paymentAttempts += outcome.attemptsUsed;
+			const releaseLock = await acquirePaymentLock(walletAddress);
+
+			try {
+				const amountUsd =
+					parseInt(requirement.maxAmountRequired, 10) / 1_000_000;
+				callbacks.onPaymentRequired?.(amountUsd);
+
+				const outcome = await handlePayment({
+					requirement,
+					keypair,
+					rpcURL,
+					baseURL,
+					baseFetch,
+					buildWalletHeaders,
+					maxAttempts: remainingPayments,
+					callbacks,
+				});
+
+				const newTotal = currentAttempts + outcome.attemptsUsed;
+				globalPaymentAttempts.set(walletAddress, newTotal);
+			} finally {
+				releaseLock();
+			}
 		}
 
 		throw new Error('Solforge: max attempts exceeded');
@@ -183,7 +327,7 @@ export function createSolforgeModel(
 		apiKey: 'solforge-wallet-auth',
 		fetch: customFetch,
 	});
-	return openai(model);
+	return openai.responses(model);
 }
 
 function trimTrailingSlash(url: string) {
@@ -202,7 +346,6 @@ type PaymentRequirementResponse = {
 
 function pickPaymentRequirement(
 	payload: unknown,
-	targetAmount: string,
 ): ExactPaymentRequirement | null {
 	const acceptsValue =
 		typeof payload === 'object' && payload !== null
@@ -211,17 +354,7 @@ function pickPaymentRequirement(
 	const accepts = Array.isArray(acceptsValue)
 		? (acceptsValue as ExactPaymentRequirement[])
 		: [];
-	const exactMatch = accepts.find(
-		(option) =>
-			option &&
-			option.scheme === 'exact' &&
-			option.maxAmountRequired === targetAmount,
-	);
-	if (exactMatch) return exactMatch;
-	const fallback = accepts.find(
-		(option) => option && option.scheme === 'exact',
-	);
-	return fallback ?? null;
+	return accepts.find((option) => option && option.scheme === 'exact') ?? null;
 }
 
 async function handlePayment(args: {
@@ -318,6 +451,7 @@ async function processSinglePayment(args: {
 		args.callbacks.onPaymentComplete?.({
 			amountUsd,
 			newBalance,
+			transactionId: parsed.transaction,
 		});
 		console.log(
 			`Solforge payment complete: +$${amountUsd} (balance: $${newBalance})`,
@@ -360,3 +494,148 @@ async function createPaymentPayload(args: {
 		},
 	} as PaymentPayload;
 }
+
+export type SolforgeBalanceResponse = {
+	walletAddress: string;
+	balance: number;
+	totalSpent: number;
+	totalTopups: number;
+	requestCount: number;
+	createdAt?: string;
+	lastRequest?: string;
+};
+
+export async function fetchSolforgeBalance(
+	auth: SolforgeAuth,
+	baseURL?: string,
+): Promise<SolforgeBalanceResponse | null> {
+	try {
+		const privateKeyBytes = bs58.decode(auth.privateKey);
+		const keypair = Keypair.fromSecretKey(privateKeyBytes);
+		const walletAddress = keypair.publicKey.toBase58();
+		const url = trimTrailingSlash(baseURL ?? DEFAULT_BASE_URL);
+
+		const nonce = Date.now().toString();
+		const signature = signNonce(nonce, privateKeyBytes);
+
+		const response = await fetch(`${url}/v1/balance`, {
+			headers: {
+				'x-wallet-address': walletAddress,
+				'x-wallet-nonce': nonce,
+				'x-wallet-signature': signature,
+			},
+		});
+
+		if (!response.ok) {
+			return null;
+		}
+
+		const data = (await response.json()) as {
+			wallet_address: string;
+			balance_usd: number;
+			total_spent: number;
+			total_topups: number;
+			request_count: number;
+			created_at?: string;
+			last_request?: string;
+		};
+
+		return {
+			walletAddress: data.wallet_address,
+			balance: data.balance_usd,
+			totalSpent: data.total_spent,
+			totalTopups: data.total_topups,
+			requestCount: data.request_count,
+			createdAt: data.created_at,
+			lastRequest: data.last_request,
+		};
+	} catch {
+		return null;
+	}
+}
+
+export function getPublicKeyFromPrivate(privateKey: string): string | null {
+	try {
+		const privateKeyBytes = bs58.decode(privateKey);
+		const keypair = Keypair.fromSecretKey(privateKeyBytes);
+		return keypair.publicKey.toBase58();
+	} catch {
+		return null;
+	}
+}
+
+const USDC_MINT_MAINNET = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const USDC_MINT_DEVNET = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU';
+
+export type SolanaUsdcBalanceResponse = {
+	walletAddress: string;
+	usdcBalance: number;
+	network: 'mainnet' | 'devnet';
+};
+
+export async function fetchSolanaUsdcBalance(
+	auth: SolforgeAuth,
+	network: 'mainnet' | 'devnet' = 'mainnet',
+): Promise<SolanaUsdcBalanceResponse | null> {
+	try {
+		const privateKeyBytes = bs58.decode(auth.privateKey);
+		const keypair = Keypair.fromSecretKey(privateKeyBytes);
+		const walletAddress = keypair.publicKey.toBase58();
+
+		const rpcUrl =
+			network === 'devnet' ? 'https://api.devnet.solana.com' : DEFAULT_RPC_URL;
+
+		const usdcMint =
+			network === 'devnet' ? USDC_MINT_DEVNET : USDC_MINT_MAINNET;
+
+		const response = await fetch(rpcUrl, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				jsonrpc: '2.0',
+				id: 1,
+				method: 'getTokenAccountsByOwner',
+				params: [walletAddress, { mint: usdcMint }, { encoding: 'jsonParsed' }],
+			}),
+		});
+
+		if (!response.ok) {
+			return null;
+		}
+
+		const data = (await response.json()) as {
+			result?: {
+				value?: Array<{
+					account: {
+						data: {
+							parsed: {
+								info: {
+									tokenAmount: {
+										uiAmount: number;
+									};
+								};
+							};
+						};
+					};
+				}>;
+			};
+		};
+
+		const accounts = data.result?.value ?? [];
+		let totalUsdcBalance = 0;
+
+		for (const account of accounts) {
+			const uiAmount =
+				account.account.data.parsed.info.tokenAmount.uiAmount ?? 0;
+			totalUsdcBalance += uiAmount;
+		}
+
+		return {
+			walletAddress,
+			usdcBalance: totalUsdcBalance,
+			network,
+		};
+	} catch {
+		return null;
+	}
+}