Comenzando con x402

El protocolo x402 (también conocido como L402) es un estándar emergente para la monetización de API que permite el acceso por uso sin requerir una suscripción.

Punto de enlace x402 de Minara: https://x402.minara.ai

¿Qué es x402?

x402 es un sistema nativo de "pago por uso" para la web. En lugar de pagar por adelantado una suscripción, pagas por cada llamada a la API directamente usando stablecoins como $USDC.

Beneficios clave:

• No se requiere suscripción: Paga solo por lo que usas

• Acceso sin permisos: No hay creación de cuenta ni proceso de aprobación

• Activación instantánea: Comienza a usar las API inmediatamente después del pago

• Nativo de cripto: Pagos en USDC en Base, Solana o Polygon

• Precios transparentes: Sabe exactamente cuánto cuesta cada llamada a la API

Cómo funciona:

El protocolo x402 sigue un flujo de pago-desafío con estos pasos clave:

El flujo completo

1. Solicitud inicial (Cliente → Servidor)

   • Realizas una solicitud de API a un endpoint protegido sin pago

2. Desafío de pago (Servidor → Cliente)

   • El servidor responde con 402 Payment Required estado

   • Devuelve instrucciones de pago (monto, moneda, dirección del beneficiario, cadena)

3. Selección de pago (Cliente)

   • Seleccionas un método de pago y creas una carga útil de pago

   • Prepárate para pagar con USDC en la cadena especificada

4. Solicitud autenticada (Cliente → Servidor)

   • Incluye la prueba de pago en x-payment-response encabezado

   • Reintenta la solicitud original

5. Verificación (Servidor → Facilitador)

   • El servidor envía la prueba de pago al facilitador para su verificación

   • Confirma la validez del pago

6. Procesamiento del pago (Facilitador → Blockchain)

   • El facilitador envía la transacción a la blockchain

   • Transacción confirmada on-chain

7. Liquidación (Facilitador → Servidor)

   • El facilitador confirma la liquidación al servidor

   • El pago se finaliza

8. Acceso concedido (Servidor → Cliente)

   • Recibes la respuesta de la API

   • Recibo de pago incluido en X-PAYMENT-RESPONSE encabezado

Componentes clave

• Cliente: Tu aplicación que realiza solicitudes a la API

• Servidor: Endpoints de la API de Minara (https://x402.minara.ai)

• Facilitador: Servicio de verificación y liquidación de pagos

• Blockchain: Liquidación de pagos on-chain (Base, Solana o Polygon)

---

Cómo usar x402 con Minara

1. Usar el SDK x402 (Recomendado)

La mayoría de los desarrolladores usan el SDK oficial x402 que gestiona todos los flujos de pago automáticamente.

Solo haces solicitudes: el SDK maneja los desafíos de pago, la verificación y la liquidación por ti.

Requisitos previos

Antes de comenzar, asegúrate de tener:

• Una billetera cripto con USDC (cualquier billetera compatible con EVM)

• Node.js y npm, Go, o Python y pip

• La clave privada de tu billetera (para firmar pagos)

Paso 1: Instalar dependencias

Node.js / TypeScript

# Para clientes basados en fetch (recomendado)
npm install @x402/fetch @x402/evm

# Para clientes basados en axios
npm install @x402/axios @x402/evm

# Para soporte de Solana, también agrega:
npm install @x402/svm

Python

# Para httpx (async) - recomendado
pip install "x402[httpx]"

# Para requests (sync)
pip install "x402[requests]"

# Para soporte de Solana, también agrega:
pip install "x402[svm]"

Go

go get github.com/coinbase/x402/go

Paso 2: Configura tu firmante de billetera

Node.js (usando viem)

npm install viem

import { privateKeyToAccount } from "viem/accounts";

// Crea un firmante desde la clave privada (usa variable de entorno)
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

Para Solana:

import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

const svmSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);

Python (usando eth-account)

pip install eth_account

import os
from eth_account import Account
from x402.mechanisms.evm import EthAccountSigner

account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
signer = EthAccountSigner(account)

Go

import (
    evmsigners "github.com/coinbase/x402/go/signers/evm"
)

evmSigner, err := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))
if err != nil {
    log.Fatal(err)
}

Paso 3: ¡Haz solicitudes: los pagos se manejan automáticamente!

El SDK maneja automáticamente los desafíos de pago por ti. ¡Solo realiza solicitudes normalmente!

Node.js (con fetch)

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// Crea firmante
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// Crea cliente x402 y registra el esquema EVM
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// Envuelve fetch con el manejo de pagos
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// Haz la solicitud - ¡el pago se maneja automáticamente! 🎉
const response = await fetchWithPayment("https://x402.minara.ai/x402/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    userQuery: "¿Cuál es el precio actual de BTC?"
  })
});

const data = await response.json();
console.log("Response:", data.content);

// Obtén el recibo de pago (opcional)
if (response.ok) {
  const httpClient = new x402HTTPClient(client);
  const paymentResponse = httpClient.getPaymentSettleResponse(
    (name) => response.headers.get(name)
  );
  console.log("Payment settled:", paymentResponse);
}

📖 Ejemplo completo en GitHub

Node.js (con axios)

import { x402Client, wrapAxiosWithPayment } from "@x402/axios";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import axios from "axios";

// Crea firmante
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// Crea cliente x402 y registra el esquema EVM
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// Crea una instancia de Axios con manejo de pagos
const api = wrapAxiosWithPayment(
  axios.create({ baseURL: "https://x402.minara.ai" }),
  client
);

// Haz la solicitud - ¡el pago se maneja automáticamente! 🎉
const response = await api.post("/x402/chat", {
  userQuery: "Analiza la acción de precio de ETH"
});

console.log("Response:", response.data.content);

📖 Ejemplo completo en GitHub

Python (async con httpx)

import asyncio
import os
from eth_account import Account

from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


async def call_minara():
    # Crea cliente y registra el esquema EVM
    client = x402Client()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    # Haz la solicitud - ¡el pago se maneja automáticamente! 🎉
    async with x402HttpxClient(client) as http:
        response = await http.post(
            "https://x402.minara.ai/x402/chat",
            json={"userQuery": "¿Cuál es el precio de BTC?"}
        )
        await response.aread()
        
        data = response.json()
        print(f"Response: {data['content']}")


asyncio.run(call_minara())

📖 Ejemplo completo en GitHub

Python (sync con requests)

import os
from eth_account import Account

from x402 import x402ClientSync
from x402.http.clients import x402_requests
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


def call_minara():
    # Crea cliente y registra el esquema EVM
    client = x402ClientSync()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    # Haz la solicitud - ¡el pago se maneja automáticamente! 🎉
    with x402_requests(client) as session:
        response = session.post(
            "https://x402.minara.ai/x402/chat",
            json={"userQuery": "¿Cuál es el precio de BTC?"}
        )
        
        data = response.json()
        print(f"Response: {data['content']}")


call_minara()

📖 Ejemplo completo en GitHub

Go

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "time"

    x402 "github.com/coinbase/x402/go"
    x402http "github.com/coinbase/x402/go/http"
    evm "github.com/coinbase/x402/go/mechanisms/evm/exact/client"
    evmsigners "github.com/coinbase/x402/go/signers/evm"
)

func main() {
    // Crea firmante EVM
    evmSigner, _ := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))

    // Crea cliente x402 y registra el esquema EVM
    x402Client := x402.Newx402Client().
        Register("eip155:*", evm.NewExactEvmScheme(evmSigner))

    // Envuelve el cliente HTTP con manejo de pagos
    httpClient := x402http.WrapHTTPClientWithPayment(
        http.DefaultClient,
        x402http.Newx402HTTPClient(x402Client),
    )

    // Prepara el cuerpo de la solicitud
    reqBody := map[string]string{"userQuery": "¿Cuál es el precio de BTC?"}
    jsonData, _ := json.Marshal(reqBody)

    // Haz la solicitud - ¡el pago se maneja automáticamente! 🎉
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    req, _ := http.NewRequestWithContext(ctx, "POST", "https://x402.minara.ai/x402/chat", bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    
    resp, err := httpClient.Do(req)
    if err != nil {
        fmt.Printf("Request failed: %v\n", err)
        return
    }
    defer resp.Body.Close()

    var data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)
    fmt.Printf("Response: %v\n", data["content"])
}

📖 Ejemplo completo en GitHub

Soporte multi-cadena (Base + Solana + Polygon)

Puedes registrar múltiples esquemas de pago para soportar todas las cadenas de Minara:

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { registerExactSvmScheme } from "@x402/svm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

// Crea firmantes para diferentes cadenas
const evmSigner = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const svmSigner = await createKeyPairSignerFromBytes(
  base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);

// Crea cliente con múltiples esquemas
const client = new x402Client();
registerExactEvmScheme(client, { signer: evmSigner });  // Base + Polygon
registerExactSvmScheme(client, { signer: svmSigner });  // Solana

const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// ¡Ahora puedes llamar a CUALQUIER endpoint de Minara! 🚀
// Endpoints de Base
await fetchWithPayment("https://x402.minara.ai/x402/chat", {...});

// Endpoints de Solana  
await fetchWithPayment("https://x402.minara.ai/x402/solana/chat", {...});

// Endpoints de Polygon
await fetchWithPayment("https://x402.minara.ai/x402/polygon/chat", {...});

Ejemplo completo: Chat con Minara

Aquí hay un ejemplo completo y funcional que llama al endpoint de chat de IA de Minara:

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

async function chatWithMinara(query: string) {
  // 1. Configura el firmante
  const signer = privateKeyToAccount(
    process.env.EVM_PRIVATE_KEY as `0x${string}`
  );

  // 2. Crea cliente x402
  const client = new x402Client();
  registerExactEvmScheme(client, { signer });

  // 3. Envuelve fetch
  const fetchWithPayment = wrapFetchWithPayment(fetch, client);

  // 4. Haz la solicitud - ¡el SDK maneja el pago automáticamente!
  const response = await fetchWithPayment("https://x402.minara.ai/x402/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ userQuery: query })
  });

  const data = await response.json();
  return data.content;
}

// Uso
const answer = await chatWithMinara("¿Cuál es el precio actual de BTC?");
console.log(answer);
// Salida: "BTC se cotiza actualmente en $98,450. Niveles clave de soporte..."

Para más información, por favor consulta la documentación oficial de x402: Inicio rápido para compradores

---

2. Flujo de pago manual (sin SDK)

Si prefieres no usar el SDK, puedes manejar los pagos manualmente:

Paso 1: Haz la solicitud inicial

curl -X POST https://x402.minara.ai/x402/chat \
  -H "Content-Type: application/json" \
  -d '{"userQuery": "¿Cuál es el precio de BTC?"}'

Paso 2: Recibe el desafío de pago

{
  "error": "payment_required",
  "message": "Se requiere pago para acceder a este recurso",
  "paymentInstructions": {
    "amount": "0.20",
    "currency": "USDC",
    "recipient": "0xCF5815e9063FA0b04Be0Cb5C1DB583eeF9ef5fbB",
    "chain": "base"
  }
}

Paso 3: Paga con la billetera

Usa MetaMask, Phantom o cualquier billetera Web3 para enviar USDC a la dirección del beneficiario.

Paso 4: Reintenta con la prueba de pago

curl -X POST https://x402.minara.ai/x402/chat \
  -H "x-payment-response: <payment_proof_token>" \
  -H "Content-Type: application/json" \
  -d '{"userQuery": "¿Cuál es el precio de BTC?"}'

Paso 5: Obtén la respuesta

{
  "content": "BTC se cotiza actualmente en $98,450..."
}

---

Manejo de errores

Errores comunes de la API de Minara

402 Payment Required

{ "error": "payment_required" }

→ ¡Normal! El SDK manejará esto automáticamente.

401 Unauthorized

{ "error": "unauthorized", "message": "Token de respuesta de pago inválido" }

→ Prueba de pago inválida o expirada. El SDK reintentará.

400 Bad Request

{ "error": "bad_request", "message": "Falta el parámetro requerido: userQuery" }

→ Verifica que el cuerpo de tu solicitud tenga los campos requeridos.

Límites de solicitud

Los endpoints x402 tienen límite de tasa por dirección de billetera:

• Endpoints de IA: 60 solicitudes/minuto

• Endpoints de trading: 30 solicitudes/minuto

Si excedes los límites:

{
  "error": "rate_limit_exceeded",
  "message": "Demasiadas solicitudes. Por favor intenta de nuevo en 30 segundos.",
  "retryAfter": 30
}

---

Recursos y soporte

📚 Recursos oficiales de x402

• Documentación del protocolo x402

• Inicio rápido para compradores

• Repositorio de x402 en GitHub

• Discord de x402

📦 Paquetes NPM

• @x402/fetch - Wrapper de Fetch

• @x402/axios - Interceptor de Axios

• @x402/evm - Soporte EVM (Base, Polygon)

• @x402/svm - Soporte Solana

• Paquete x402 para Python

🔍 Específico de Minara

• Minara en x402scan - Ver todos los endpoints

• Referencia de la API de Minara (x402) - Referencia de la API (x402)

Referencia de la API

Referencia de la API (x402)