stellar-sdk-examples

Scripts ejecutables en Node + TypeScript que muestran cómo usar el SDK oficial @stellar/stellar-sdk contra la testnet de Stellar.

Cada script bajo src/ es un ejemplo independiente — pensados para leerse y correrse uno por uno. Todos usan el RPC público de testnet (https://soroban-testnet.stellar.org) y, para consultar balances, Horizon (https://horizon-testnet.stellar.org).

Requisitos

• Node.js 18 o superior (necesitamos fetch global y soporte ESM)
• npm

Instalación

git clone <repo>
cd stellar-sdk-examples
npm install
cp .env.example .env

Empezar de cero

Si no tienes cuenta en testnet todavía:

# 1. Generar un keypair nuevo
npx tsx src/01-generate-keypair.ts

# 2. Fondear el pubkey que imprimió
npx tsx src/02-fund-friendbot.ts G...

# 3. Pegar la clave secreta en .env como SENDER_SECRET
#    y un destinatario distinto (otro pubkey ya fondeado) en DESTINATION_PUBLIC_KEY

A partir de ahí, los ejemplos que firman transacciones leen SENDER_SECRET y DESTINATION_PUBLIC_KEY desde .env.

Variables de entorno

Variable	Usado por	Descripción
SENDER_SECRET	04, 05*, 06, 07, 09	Clave secreta (S...) del emisor
DESTINATION_PUBLIC_KEY	04, 06, 07, 09	Clave pública (G...) del destinatario
FUNDER_SECRET	05 (opcional)	Si se omite, usa SENDER_SECRET
NEW_ACCOUNT_PUBLIC_KEY	05 (opcional)	Si se omite, se genera un keypair nuevo y se imprime
STARTING_BALANCE	05 (opcional)	XLM iniciales para la nueva cuenta (default 2)
QUERY_PUBLIC_KEY	02, 03 (opcional)	Si se omite, 03 usa el pubkey de SENDER_SECRET
ASSET_CODE	07 (opcional)	Default USDC
ASSET_ISSUER	07 (opcional)	Default: emisor de USDC de Circle en testnet
AMOUNT	04, 06, 07, 09 (opcional)	Cantidad a enviar (default varía por ejemplo)
MEMO_TEXT	06 (opcional)	Default "Pago factura #1234"

Ejecutar los ejemplos

#	Script	Comando	Necesita .env
1	Generar keypair	npx tsx src/01-generate-keypair.ts	No
2	Fondear cuenta con Friendbot	npx tsx src/02-fund-friendbot.ts [PUBLIC_KEY]	No (opcional)
3	Consultar balance	npx tsx src/03-get-balance.ts [PUBLIC_KEY]	No (opcional)
4	Enviar pago de XLM	npx tsx src/04-send-payment.ts	Sí
5	Crear cuenta nueva	npx tsx src/05-create-account.ts	Sí
6	Enviar pago con memo	npx tsx src/06-send-with-memo.ts	Sí
7	Enviar activo custom (USDC)	npx tsx src/07-send-custom-asset.ts	Sí (+ trustline)
8	Conectar con Freighter (browser)	npx tsx src/08-freighter-wallet.ts	N/A (browser-only)
9	Esperar confirmación	npx tsx src/09-wait-for-confirmation.ts	Sí
10	Demo extremo a extremo	npx tsx src/10-full-demo.ts	No

También hay alias en npm run:

npm run example:01
npm run example:10
npm run typecheck   # solo verifica TS, no corre nada

Notas y advertencias

• Monto como string — siempre "10", nunca 10. JS pierde precisión con decimales.
• El ejemplo 8 es solo navegador. Freighter es una extensión, así que el script imprime una explicación y termina. Lee el archivo para el snippet completo y úsalo desde una app frontend (Vite, Next.js, etc.).
• El ejemplo 7 requiere trustline. La cuenta destinataria tiene que haber confiado en el activo (USDC) antes; si no, la transacción falla con tx_failed / op_no_trust.
• RPC vs. Horizon. El RPC no devuelve balances en getAccount(), por eso el ejemplo 3 (y el demo final) consultan Horizon. Para construir y firmar transacciones seguimos usando el RPC.
• Testnet se resetea ocasionalmente. No uses estas claves en mainnet ni guardes nada importante en ellas.
• Sequence numbers. El SDK los maneja al cargar la cuenta con server.getAccount(). Si lanzas dos transacciones en paralelo desde la misma cuenta, la segunda fallará — recarga la cuenta entre cada una.

Recursos

• SDK en npm
• Stellar Lab
• Explorador testnet
• Friendbot