Guía de Omniston (Python)

Aprende a crear un cliente de terminal basado en Python para intercambiar tokens en la blockchain TON usando el protocolo Omniston. Cubre la configuración de la wallet, la integración de la API y los swaps entre DEX en STON.fi y DeDust.

Esta guía te llevará a crear un basado en terminal cliente de intercambio de tokens usando el Omniston protocolo para intercambiar activos entre diferentes DEXes (STON.fi V1, STON.fi V2, DeDust, etc.). En lugar de una interfaz web y TonConnect, usaremos una billetera local de TON (creada con tonsdk) y enviaremos transacciones mediante Toncenter. La guía es apta para principiantes y asume una experiencia mínima con TON.

Nota: Este inicio rápido usa intencionalmente un CLI de un solo archivo por claridad. Más adelante puedes modularizarlo o empaquetarlo (consulta Aplicación de ejemplo avanzada).

Nota: Para mayor confiabilidad al transmitir transacciones, establece una TONCENTER_API_KEY (consulta Configurar activos y red).

---

Índice

1. Introducción

2. Configuración del proyecto

3. Configuración de la billetera

4. Configurar activos y red

5. Implementación del CLI (paso a paso)

6. Solicitar una cotización

7. Construcción de una transacción y envío

8. Probar tu intercambio

9. Conclusión

10. Demo en vivo

11. Uso de agentes de IA para la implementación automatizada

---

1. Introducción

En este inicio rápido, construirás un CLI de Python mínimo que puede:

• Crear o reutilizar una billetera local de TON (mediante tonsdk).

• Cargar la red y la configuración de tokens desde .env y swap_config.json.

• Solicitar un RFQ (cotización) de Omniston a través de WebSockets.

• Construir una transferencia usando el generador de transacciones de Omniston.

• Enviar la transacción a Toncenter para ejecutar el intercambio.

Usarás:

• tonsdk – generación de billeteras, firma y BOCs.

• websockets – para comunicarte con Omniston.

• python-dotenv – para cargar variables de entorno.

• API de Toncenter – para transmitir la transacción firmada.

---

2. Configuración del proyecto

2.1 Crea el espacio de trabajo

mkdir omniston-python
cd omniston-python

2.2 Crea el entorno virtual

python3 -m venv .venv
source .venv/bin/activate        # macOS/Linux
# .venv\\Scripts\\Activate.ps1  # Windows PowerShell

2.3 Instala las dependencias

1. Crea requirements.txt y agrega:

   python-dotenv>=1.0,<2
   tonsdk>=1.0.13
   websockets>=11,<13

2. Instala los paquetes:

   pip install -r requirements.txt

3. Crea un script CLI de un solo archivo:

   touch omniston_cli.py

---

3. Configuración de la billetera

El CLI guarda de forma persistente una billetera en data/wallet.json y muestra una frase mnemónica una sola vez—guárdala de forma segura.

3.1 Genera o carga una billetera

En este paso pegarás las definiciones principales y los ayudantes de la billetera (mantenidos en la parte superior de omniston_cli.py).

Consejo: Los bloques de código a continuación son exactamente los de la implementación funcional; pégalos tal cual y en el orden indicado.

3.2 Financia e implementa la billetera

Debes financiar la dirección e implementar el contrato de la billetera antes de enviar un intercambio. Los ayudantes de abajo se encargan de consultar Toncenter y enviar el BOC de inicialización cuando sea necesario.

---

4. Configurar activos y red

Definirás los extremos RPC y el par de intercambio predeterminado localmente.

4.1 Crea el archivo .env

Crea .env en la raíz del proyecto:

TONCENTER_API_URL=https://toncenter.com/api/v2
TONCENTER_API_KEY=put-your-api-key-here
OMNISTON_WS_URL=wss://omni-ws.ston.fi

Obtener una clave de API de Toncenter: Usar la API sin una clave de API está limitado a 1 solicitud por segundo. Para obtener límites de velocidad más altos:

1. Contacta a @toncenter en Telegram

2. Solicita una clave de API para tu proyecto

3. Copia la clave y pégala en tu .env archivo

TONCENTER_API_KEY es necesario si quieres ejecutar transacciones. Sin él, te enfrentarás a problemas de limitación de velocidad y la transmisión de transacciones fallará.

4.2 Define el swap_config.json

Crea swap_config.json:

{
  "from_token_address": "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c",
  "from_token_decimals": 9,
  "to_token_address": "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO",
  "to_token_decimals": 9,
  "amount": "0.01",
  "max_slippage_bps": 500,
  "max_outgoing_messages": 4,
  "gasless_mode": "GASLESS_SETTLEMENT_POSSIBLE",
  "flexible_referrer_fee": false
}

Direcciones comunes de tokens:

• TON nativo: EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c

• USDT: EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs

• STON: EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO

gasless_mode acepta "GASLESS_SETTLEMENT_UNSPECIFIED", "GASLESS_SETTLEMENT_POSSIBLE", "GASLESS_SETTLEMENT_REQUIRED", o sus equivalentes numéricos 0/1/2.

flexible_referrer_fee permite que Omniston reduzca la comisión real del referidor por debajo de referrer_fee_bps cuando un resolutor puede ofrecer un mejor precio. Déjalo false para imponer la comisión exacta.

---

5. Implementación del CLI (paso a paso)

Abre omniston_cli.py y pega los bloques de ayudantes restantes a continuación exactamente como se muestran.

5.1 Define los tipos de dominio

# omniston_cli.py
import asyncio
import base64
import json
import os
import sys
import time
import urllib.parse
import urllib.request
import uuid
from dataclasses import dataclass
from decimal import Decimal, ROUND_DOWN, getcontext
from pathlib import Path
from typing import Dict, List, Optional, Tuple

import websockets
from dotenv import load_dotenv
from tonsdk.boc import Cell
from tonsdk.contract.wallet import Wallets, WalletVersionEnum
from tonsdk.crypto import mnemonic_new
from tonsdk.utils import bytes_to_b64str


DATA_DIR = Path("data")
WALLET_FILE = DATA_DIR / "wallet.json"
CONFIG_FILE = Path("swap_config.json")


@dataclass
class WalletData:
    mnemonic: List[str]
    address_hex: str
    address_bounceable: str
    workchain: int
    version: str

    def to_dict(self) -> Dict[str, object]:
        return {
            "mnemonic": self.mnemonic,
            "address_hex": self.address_hex,
            "address_bounceable": self.address_bounceable,
            "workchain": self.workchain,
            "version": self.version,
        }

    @classmethod
    def from_dict(cls, payload: Dict[str, object]) -> "WalletData":
        return cls(
            mnemonic=list(payload["mnemonic"]),
            address_hex=str(payload["address_hex"]),
            address_bounceable=str(payload.get("address_bounceable", "")),
            workchain=int(payload.get("workchain", 0)),
            version=str(payload.get("version", WalletVersionEnum.v4r2.value)),
        )


@dataclass
class SwapConfig:
    from_token_address: str
    from_token_decimals: int
    to_token_address: str
    to_token_decimals: int
    amount: Decimal
    max_slippage_bps: int
    max_outgoing_messages: int
    gasless_mode: int
    flexible_referrer_fee: bool


GASLESS_SETTLEMENT_MAP = {
    "GASLESS_SETTLEMENT_UNSPECIFIED": 0,
    "GASLESS_SETTLEMENT_POSSIBLE": 1,
    "GASLESS_SETTLEMENT_REQUIRED": 2,
}


def _parse_gasless_mode(raw: object) -> int:
    if isinstance(raw, int):
        return raw
    if isinstance(raw, str):
        token = raw.strip()
        if not token:
            return 1
        upper = token.upper()
        if upper in GASLESS_SETTLEMENT_MAP:
            return GASLESS_SETTLEMENT_MAP[upper]
        return int(token)
    raise TypeError("gasless_mode must be str or int")


def load_config() -> SwapConfig:
    if not CONFIG_FILE.exists():
        raise FileNotFoundError("swap_config.json is missing")
    with CONFIG_FILE.open("r", encoding="utf-8") as handle:
        payload = json.load(handle)
    gasless_mode = _parse_gasless_mode(payload.get("gasless_mode", "GASLESS_SETTLEMENT_POSSIBLE"))
    return SwapConfig(
        from_token_address=str(payload["from_token_address"]),
        from_token_decimals=int(payload["from_token_decimals"]),
        to_token_address=str(payload["to_token_address"]),
        to_token_decimals=int(payload["to_token_decimals"]),
        amount=Decimal(str(payload["amount"])),
        max_slippage_bps=int(payload.get("max_slippage_bps", 500)),
        max_outgoing_messages=int(payload.get("max_outgoing_messages", 4)),
        gasless_mode=gasless_mode,
        flexible_referrer_fee=bool(payload.get("flexible_referrer_fee", False)),
    )


def ensure_data_dir() -> None:
    DATA_DIR.mkdir(parents=True, exist_ok=True)


def prompt_yes_no(message: str, default: bool = False) -> bool:
    suffix = " [Y/n]" if default else " [y/N]"
    while True:
        reply = input(f"{message}{suffix} ").strip().lower()
        if not reply:
            return default
        if reply in {"y", "yes"}:
            return True
        if reply in {"n", "no"}:
            return False


getcontext().prec = 28
# ID de cadena de la blockchain TON usado por el protocolo Omniston
BLOCKCHAIN_ID = 607  # Representa la blockchain TON (equivalente a Blockchain.TON en los SDKs)
QUOTE_TIMEOUT = 15
TRANSFER_TIMEOUT = 30


TONCENTER_API_URL = "https://toncenter.com/api/v2"
TONCENTER_API_KEY = ""
OMNISTON_WS_URL = "wss://omni-ws.ston.fi"


def load_env() -> None:
    global TONCENTER_API_URL, TONCENTER_API_KEY, OMNISTON_WS_URL
    load_dotenv()
    TONCENTER_API_URL = os.getenv("TONCENTER_API_URL", TONCENTER_API_URL)
    TONCENTER_API_KEY = os.getenv("TONCENTER_API_KEY", TONCENTER_API_KEY)
    OMNISTON_WS_URL = os.getenv("OMNISTON_WS_URL", OMNISTON_WS_URL)

5.2 Ayudantes de la billetera

def save_wallet(wallet: WalletData) -> None:
    ensure_data_dir()
    with WALLET_FILE.open("w", encoding="utf-8") as handle:
        json.dump(wallet.to_dict(), handle, indent=2)


def load_wallet() -> Optional[WalletData]:
    if not WALLET_FILE.exists():
        return None
    with WALLET_FILE.open("r", encoding="utf-8") as handle:
        payload = json.load(handle)
    return WalletData.from_dict(payload)


def ensure_wallet() -> WalletData:
    ensure_data_dir()
    wallet = load_wallet()
    if wallet:
        print(f"Cargada la billetera desde {WALLET_FILE}")
        return wallet

    mnemonic = mnemonic_new()
    version = WalletVersionEnum.v4r2
    _, _, _, contract = Wallets.from_mnemonics(mnemonic, version, 0)
    wallet = WalletData(
        mnemonic=mnemonic,
        address_hex=contract.address.to_string(False),
        address_bounceable=contract.address.to_string(True, True, False),
        workchain=contract.address.wc,
        version=version.value,
    )
    save_wallet(wallet)
    print(f"Nueva billetera creada en {WALLET_FILE}")
    print("Frase mnemónica (guárdala de forma segura):")
    print(" ".join(wallet.mnemonic))
    return wallet


def build_init_boc(wallet: WalletData) -> str:
    version = WalletVersionEnum(wallet.version)
    _, _, _, contract = Wallets.from_mnemonics(wallet.mnemonic, version, wallet.workchain)
    message = contract.create_init_external_message()["message"]
    return bytes_to_b64str(message.to_boc(False))

5.3 Ayudantes de Toncenter

def toncenter_get(endpoint: str, params: Dict[str, object]) -> Dict[str, object]:
    query = dict(params)
    if TONCENTER_API_KEY:
        query.setdefault("api_key", TONCENTER_API_KEY)
    url = f"{TONCENTER_API_URL.rstrip('/')}/{endpoint}"
    if query:
        url = f"{url}?{urllib.parse.urlencode(query)}"
    request = urllib.request.Request(url, headers={"Accept": "application/json"})
    with urllib.request.urlopen(request, timeout=15) as response:
        return json.loads(response.read().decode("utf-8"))


def toncenter_post(endpoint: str, body: Dict[str, object]) -> Dict[str, object]:
    query = {}
    if TONCENTER_API_KEY:
        query["api_key"] = TONCENTER_API_KEY
    url = f"{TONCENTER_API_URL.rstrip('/')}/{endpoint}"
    if query:
        url = f"{url}?{urllib.parse.urlencode(query)}"
    data = json.dumps(body).encode("utf-8")
    request = urllib.request.Request(
        url,
        data=data,
        headers={"Accept": "application/json", "Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(request, timeout=15) as response:
        return json.loads(response.read().decode("utf-8"))


def send_boc(boc_base64: str) -> bool:
    response = toncenter_post("sendBoc", {"boc": boc_base64})
    return bool(response.get("ok", True))


def fetch_balance(address: str) -> Optional[Decimal]:
    try:
        result = toncenter_get("getAddressBalance", {"address": address})
    except Exception as exc:
        print(f"No se pudo obtener el saldo: {exc}")
        return None
    raw = result.get("result")
    if raw is None:
        return None
    return Decimal(str(raw)) / Decimal(1_000_000_000)


def lookup_wallet_seqno(address: str) -> Optional[int]:
    try:
        result = toncenter_get("getWalletInformation", {"address": address})
    except Exception:
        return None
    data = result.get("result")
    if not data:
        return None
    seqno = data.get("seqno")
    return int(seqno) if seqno is not None else None


def ensure_wallet_deployed(wallet: WalletData) -> bool:
    if lookup_wallet_seqno(wallet.address_hex) is not None:
        return True

    print("Implementando la billetera (requiere fondos en la dirección)...")
    if not send_boc(build_init_boc(wallet)):
        print("Toncenter rechazó el mensaje de implementación.")
        return False

    for _ in range(10):
        time.sleep(2)
        if lookup_wallet_seqno(wallet.address_hex) is not None:
            print("Implementación de la billetera confirmada.")
            return True

    print("La implementación de la billetera aún no está confirmada; inténtalo de nuevo una vez que la transacción se procese.")
    return False

5.4 Ayudantes de cotización

def _token_to_units(amount: Decimal, decimals: int) -> int:
    return int((amount * Decimal(10) ** decimals).to_integral_value(ROUND_DOWN))


def _units_to_token(units: int, decimals: int) -> Decimal:
    return Decimal(units) / (Decimal(10) ** decimals)


def format_amount(value: Decimal, decimals: int) -> str:
    quantum = Decimal("1").scaleb(-decimals)
    text = f"{value.quantize(quantum, rounding=ROUND_DOWN):f}"
    return text.rstrip("0").rstrip(".") if "." in text else text


def _extract_quote(data: Optional[Dict[str, object]]) -> Optional[Dict[str, object]]:
    if not isinstance(data, dict):
        return None
    if "bid_units" in data and "ask_units" in data:
        return data
    if "quote" in data and isinstance(data["quote"], dict):
        return data["quote"]
    for value in data.values():
        if isinstance(value, dict):
            found = _extract_quote(value)
            if found:
                return found
    return None


def _extract_event_error(data: Dict[str, object]) -> Optional[object]:
    if not isinstance(data, dict):
        return None
    if data.get("error"):
        return data["error"]

    result = data.get("result")
    if isinstance(result, dict):
        if result.get("error"):
            return result["error"]
        event_type = str(result.get("type", "")).lower()
        if "rejected" in event_type:
            return result.get("error") or result

    params = data.get("params")
    if isinstance(params, dict):
        return _extract_event_error(params)
    return None


def _format_error(error: object) -> str:
    if isinstance(error, dict):
        message = error.get("message") or error.get("reason")
        if isinstance(message, str) and message.strip():
            return message.strip()
        try:
            text = json.dumps(error)
            if text.strip():
                return text
        except Exception:
            pass
    text = str(error)
    return text if text.strip() else repr(error)


def describe_quote(quote: Dict[str, object], config: SwapConfig) -> (Decimal, str):
    ask_units = quote.get("ask_units") or quote.get("askUnits")
    bid_units = quote.get("bid_units") or quote.get("bidUnits")
    if ask_units is None or bid_units is None:
        return Decimal("0"), "La cotización no tiene unidades"

    ask_amount = _units_to_token(int(ask_units), config.to_token_decimals)
    bid_amount = _units_to_token(int(bid_units), config.from_token_decimals)
    summary = (
        f"Intercambiar {format_amount(bid_amount, config.from_token_decimals)} -> "
        f"{format_amount(ask_amount, config.to_token_decimals)}"
    )
    return ask_amount, summary


def request_quote(config: SwapConfig, wallet: WalletData) -> Dict[str, object]:
    bid_units = str(_token_to_units(config.amount, config.from_token_decimals))
    request_id = str(uuid.uuid4())
    params = {
        "bid_asset_address": {"blockchain": BLOCKCHAIN_ID, "address": config.from_token_address},
        "ask_asset_address": {"blockchain": BLOCKCHAIN_ID, "address": config.to_token_address},
        "amount": {"bid_units": bid_units},
        "referrer_fee_bps": 0,
        "settlement_methods": [0],  # 0 == SWAP
        "settlement_params": {
            "max_price_slippage_bps": config.max_slippage_bps,
            "max_outgoing_messages": config.max_outgoing_messages,
            "gasless_settlement": config.gasless_mode,
            "flexible_referrer_fee": config.flexible_referrer_fee,
            "wallet_address": {"blockchain": BLOCKCHAIN_ID, "address": wallet.address_hex},
        },
    }

    payload = {
        "jsonrpc": "2.0",
        "id": request_id,
        "method": "v1beta7.quote",
        "params": params,
    }

    async def _run() -> Dict[str, object]:
        async with websockets.connect(OMNISTON_WS_URL, ping_interval=20, ping_timeout=20) as ws:
            await ws.send(json.dumps(payload))
            deadline = time.time() + QUOTE_TIMEOUT
            print("Esperando la cotización...")
            while time.time() < deadline:
                timeout = max(0.1, deadline - time.time())
                try:
                    raw = await asyncio.wait_for(ws.recv(), timeout=timeout)
                except asyncio.TimeoutError:
                    continue
                data = json.loads(raw)
                event_error = _extract_event_error(data)
                if event_error:
                    raise RuntimeError(_format_error(event_error))
                quote = _extract_quote(data.get("result")) or _extract_quote(data)
                if quote:
                    return quote
            raise RuntimeError("Se agotó el tiempo de espera para la cotización de Omniston")

    try:
        return asyncio.run(_run())
    except Exception as exc:
        raise RuntimeError(f"La solicitud de cotización a Omniston falló: {exc!r}") from exc

5.5 Ayudantes de transferencia

def _decode_cell(raw: Optional[str]) -> Optional[Cell]:
    if raw is None:
        return None
    raw = raw.strip()
    if not raw:
        return None
    try:
        data = base64.b64decode(raw)
    except Exception:
        try:
            data = bytes.fromhex(raw)
        except ValueError:
            return None
    try:
        return Cell.one_from_boc(data)
    except Exception:
        return None


def _extract_transfer(data: Optional[Dict[str, object]]) -> Optional[Dict[str, object]]:
    if not isinstance(data, dict):
        return None
    if "ton" in data and isinstance(data["ton"], dict):
        return data
    if "transaction" in data and isinstance(data["transaction"], dict):
        return data["transaction"]
    for value in data.values():
        if isinstance(value, dict):
            found = _extract_transfer(value)
            if found:
                return found
    return None


def _build_transfer(quote: Dict[str, object], wallet: WalletData) -> Dict[str, object]:
    request_id = str(uuid.uuid4())
    params = {
        "quote": quote,
        "source_address": {"blockchain": BLOCKCHAIN_ID, "address": wallet.address_hex},
        "destination_address": {"blockchain": BLOCKCHAIN_ID, "address": wallet.address_hex},
        "gas_excess_address": {"blockchain": BLOCKCHAIN_ID, "address": wallet.address_hex},
        "use_recommended_slippage": True,
    }
    payload = {
        "jsonrpc": "2.0",
        "id": request_id,
        "method": "v1beta7.transaction.build_transfer",
        "params": params,
    }

    async def _run() -> Dict[str, object]:
        async with websockets.connect(OMNISTON_WS_URL, ping_interval=20, ping_timeout=20) as ws:
            await ws.send(json.dumps(payload))
            deadline = time.time() + TRANSFER_TIMEOUT
            while time.time() < deadline:
                raw = await asyncio.wait_for(ws.recv(), timeout=max(0.1, deadline - time.time()))
                data = json.loads(raw)
                if data.get("error"):
                    raise RuntimeError(data["error"])
                transfer = _extract_transfer(data.get("result")) or _extract_transfer(data)
                if transfer:
                    return {"jsonrpc": data.get("jsonrpc", "2.0"), "result": transfer}
            raise TimeoutError("Se agotó el tiempo de espera para construir la transferencia")

    return asyncio.run(_run())


def execute_swap(quote: Dict[str, object], wallet: WalletData) -> bool:
    if not TONCENTER_API_KEY:
        print("TONCENTER_API_KEY no configurada; no se puede enviar la transacción automáticamente.")
        return False

    try:
        transfer = _build_transfer(quote, wallet)
    except Exception as exc:
        print(f"No se pudo construir la transferencia: {exc}")
        return False

    ton_section = transfer.get("result", {}).get("ton") if isinstance(transfer, dict) else None
    messages = ton_section.get("messages") if isinstance(ton_section, dict) else None
    if not isinstance(messages, list) or not messages:
        print("No se devolvieron mensajes de transferencia.")
        return False

    msg = messages[0]
    payload_cell = _decode_cell(
        msg.get("payload")
        or msg.get("message_boc")
        or msg.get("messageBoc")
        or msg.get("boc")
    )
    state_init_cell = _decode_cell(
        msg.get("state_init") or msg.get("jetton_wallet_state_init")
    )

    seqno = lookup_wallet_seqno(wallet.address_hex)
    if seqno is None:
        print("No se pudo obtener el seqno de la wallet; asegúrate de que la wallet esté desplegada y financiada.")
        return False

    version = WalletVersionEnum(wallet.version)
    _, _, _, contract = Wallets.from_mnemonics(wallet.mnemonic, version, wallet.workchain)

    target_address = msg.get("target_address") or msg.get("address")
    amount_field = msg.get("send_amount") or msg.get("amount")
    try:
        amount_value = int(str(amount_field))
    except Exception:
        print("Cantidad de envío inválida en el mensaje de transferencia.")
        return False

    external = contract.create_transfer_message(
        target_address,
        amount_value,
        seqno,
        payload=payload_cell,
        state_init=state_init_cell,
    )

    boc = base64.b64encode(external["message"].to_boc(False)).decode("ascii")
    print("Enviando swap a través de Toncenter...")
    ok = send_boc(boc)
    print("Swap enviado." if ok else "Toncenter rechazó la transacción.")
    return ok

5.6 Punto de entrada del comando

MIN_INIT_BALANCE_TON = Decimal("0.25")


def main() -> None:
    load_env()
    config = load_config()

    print("Omniston Python Quickstart")
    print("==========================")

    wallet = ensure_wallet()
    print(f"Wallet: {wallet.address_bounceable}")

    balance = fetch_balance(wallet.address_hex) or Decimal("0")
    print(f"Balance: {format_amount(balance, 9)} TON")

    if balance < MIN_INIT_BALANCE_TON:
        need = format_amount(MIN_INIT_BALANCE_TON, 9)
        print(f"Por favor, financia tu wallet con al menos {need} TON y luego vuelve a ejecutar este script.")
        print(f"Envía TON a: {wallet.address_bounceable}")
        return

    if not ensure_wallet_deployed(wallet):
        return

    if not prompt_yes_no("¿Solicitar una cotización ahora?", default=True):
        print("Cotización omitida.")
        return

    try:
        quote = request_quote(config, wallet)
    except Exception as exc:
        print(f"La solicitud de cotización falló: {exc}")
        return

    received, summary = describe_quote(quote, config)
    if received <= Decimal("0"):
        print("La cotización devolvió una salida cero; abortando.")
        return

    if not prompt_yes_no(f"¿Intercambiar {summary}?", default=False):
        print("Swap cancelado.")
        return

    print(f"Ejecutando swap: {summary}")
    execute_swap(quote, wallet)


if __name__ == "__main__":
    main()

---

6. Solicitar una cotización

Ejecuta la CLI y sigue la indicación:

python omniston_cli.py

Cuando aceptes "¿Solicitar una cotización ahora?", la CLI:

• Construirá una solicitud usando tu par y cantidad configurados.

• Se conectará a Omniston a través de WebSockets (v1beta7.quote).

• Mostrará un resumen legible por humanos (por ejemplo, Intercambiar 0.01 -> 12.34).

Si no se puede producir una cotización a tiempo (predeterminado: ~15s), verás un mensaje de tiempo de espera o de error.

---

7. Construir una transacción y enviarla

Después de que apruebes el resumen de la cotización, la CLI:

1. Llama al constructor de transacciones de Omniston (v1beta7.transaction.build_transfer) para obtener mensajes TON.

2. Firma un mensaje externo con tu wallet.

3. Envía el BOC resultante a Toncenter.

Importante: El envío automático requiere TONCENTER_API_KEY en .env. Sin ello, la CLI omite la transmisión.

---

8. Probar tu intercambio

1. Activa tu entorno virtual y asegúrate de que .env y swap_config.json existan.

2. Financia tu wallet y ejecuta:

   python omniston_cli.py

3. Confirma:

   • La wallet se crea/carga y se imprime el saldo.

   • El despliegue se completa (o ya está desplegado).

   • Se recibe una cotización y se resume.

   • Al aprobarla, la transacción se envía y ves "Swap enviado.".

   • Revisa tu wallet en un explorador de TON para confirmar el swap.

Si algo falla, la CLI muestra un mensaje claro (por ejemplo, tiempo de espera, clave API faltante, problema de seqno).

---

9. Conclusión

Ahora tienes una CLI mínima de Python que:

• Genera o reutiliza una wallet TON.

• Carga la configuración local de activos y red.

• Solicita cotizaciones en tiempo real desde Omniston.

• Construye y envía el swap a través de Toncenter.

Ideas para ampliar:

• Banderas personalizadas de CLI (cantidad/par) con argparse.

• Mejor reporte de errores y reintentos/backoff.

• Enlaces al explorador después del envío.

• Seguimiento de operaciones con comprobaciones periódicas de estado.

10. Demostración en vivo

Ejecuta la CLI de Python de Omniston directamente en tu navegador a través de Replit:

• Abre el proyecto en Replit

• Haz un fork en tu cuenta para guardar los cambios

• Añade una TONCENTER_API_KEY en los secretos de Replit

• Ejecuta python omniston_cli.py en la shell de Replit

• Explora y modifica el código libremente

---

11. Uso de agentes de IA para la implementación automatizada

También puedes seguir una guía grabada:

Para los desarrolladores que buscan acelerar su proceso de desarrollo, pueden aprovechar agentes de programación de IA para implementar automáticamente la funcionalidad de intercambio de Omniston descrita en esta guía. Aunque mostramos Gemini CLI en nuestro ejemplo (debido a su generoso plan gratuito), puedes usar cualquier asistente de programación de IA como Claude Code, GitHub Copilot, Cursor Agent, o herramientas similares.

11.1 ¿Por qué agentes de IA?

Los modernos agentes de programación de IA pueden:

• Entender documentación compleja e implementar funciones completas

• Configurar automáticamente la estructura del proyecto y las dependencias

• Gestionar errores comunes de configuración y puesta en marcha

• Proporcionar implementaciones funcionales en minutos en lugar de horas

11.2 Configuración con Gemini CLI (ejemplo)

Haremos la demostración con Gemini CLI, pero el enfoque funciona con cualquier agente de IA que pueda leer documentación y ejecutar comandos.

11.2.1 Instalación de Gemini CLI

1. Instala Gemini CLI siguiendo las instrucciones en: https://github.com/google-gemini/gemini-cli

2. Autentícate con tu cuenta de Google cuando se te solicite. El nivel gratuito incluye:

   • 60 solicitudes al modelo por minuto

   • 1.000 solicitudes al modelo por día

11.2.2 Configuración de la guía de implementación

1. Descarga el archivo de guía adecuado desde el gist: https://gist.github.com/mrruby/a6fba69716fc0d5b8eaafd43998b36c0

   • Para Claude Code: Descarga AGENTS.md y cámbiale el nombre a CLAUDE.md

   • Para otros agentes de IA (Gemini CLI, GitHub Copilot, Cursor, etc.): Usa AGENTS.md tal cual

2. Crea un nuevo directorio para tu proyecto y coloca el archivo de guía dentro de él:

   mkdir my-omniston-swap
   cd my-omniston-swap
   # Coloca CLAUDE.md (para Claude Code) o AGENTS.md (para otros agentes) aquí

11.2.3 Ejecución de la implementación automatizada

1. Desde el directorio de tu proyecto, ejecuta Gemini CLI:

   gemini

2. Cuando se abra la interfaz de la CLI, escribe:

   Implementa el swap de Omniston según la Guía de inicio rápido de Omniston en AGENTS.md

3. El agente de IA:

   • Pedirá permiso para usar comandos como python3, pip, etc.

   • Creará automáticamente la estructura del proyecto

   • Instalará todas las dependencias necesarias

   • Implementa la funcionalidad completa de intercambio

   • Configurar archivos de configuración

4. Importante: Después de que la implementación se complete, debes configurar manualmente tu clave API de Toncenter:

   • Ve a TON Center y obtén tu clave de API

   • Crea un .env archivo en la raíz de tu proyecto

   • Añade tu clave de API: TONCENTER_API_KEY=tu_api_key_aqui

   • Los agentes de IA no pueden encargarse de este paso, ya que requiere tus credenciales personales de API

5. Si ocurre algún error durante el proceso:

   • Simplemente vuelve a pegar el mensaje de error al agente de IA

   • Analizará y corregirá el problema automáticamente

   • En la mayoría de los casos, la implementación se completa correctamente de una sola vez

11.3 Uso de otros agentes de IA

El mismo enfoque funciona con otros asistentes de programación de IA:

• Claude Code: Descarga AGENTS.md y cámbiale el nombre a CLAUDE.md, luego colócalo en tu proyecto y pide a Claude Code que implemente la guía

• GitHub Copilot: Usa el AGENTS.md archivo tal cual, abre la guía en tu editor y usa Copilot Chat para implementar paso a paso

• Cursor Agent: Usa el AGENTS.md archivo tal cual, carga la documentación y solicita la implementación completa mediante el modo agente de Cursor

• Herramientas personalizadas: Cualquier asistente de IA con acceso a archivos y capacidad de ejecutar comandos puede seguir la guía usando el AGENTS.md archivo

Nota: El AGENTS.md archivo contiene instrucciones compatibles con todos los agentes de IA (Gemini CLI, GitHub Copilot, Cursor, etc.). Sin embargo, Claude Code requiere que el archivo se llame CLAUDE.md para ser reconocido automáticamente, así que debes renombrar AGENTS.md to CLAUDE.md cuando uses Claude Code.

11.4 Beneficios de usar agentes de IA

• Velocidad: Obtén una implementación funcional en minutos en lugar de horas

• Precisión: Los agentes de IA siguen la guía rápida con exactitud

• Gestión de errores: Resuelven automáticamente la mayoría de los problemas comunes de configuración

• Herramienta de aprendizaje: Observa cómo se desarrolla la implementación paso a paso

• Personalización: Después de la configuración inicial, puedes modificar el código generado para adaptarlo a tus necesidades específicas

• Rentable: Muchas herramientas de programación con IA ofrecen niveles gratuitos (como Gemini CLI) o están incluidas en suscripciones existentes

11.5 Mejores prácticas

1. Revisar el código: Revisa siempre el código generado por IA antes de usarlo en producción

2. Entender el flujo: Usa el código generado como una herramienta de aprendizaje para comprender el protocolo de Omniston

3. Personalizar: Adapta el código generado a tus requisitos específicos

4. Probar a fondo: Prueba la implementación con cantidades pequeñas antes de procesar transacciones más grandes

5. Seguridad: Nunca confirmes claves de API ni mnemónicos en el control de versiones

Este enfoque es especialmente útil para:

• Desarrolladores nuevos en el ecosistema TON

• Prototipado rápido y pruebas de concepto

• Aprender con un ejemplo de una implementación funcional

• Evitar errores comunes de configuración y problemas de puesta en marcha

• Explorar rápidamente diferentes enfoques de implementación

---

¡Feliz intercambio!