@panal/sdk 0.1.0 → 0.4.0

package/dist/abis.d.ts

@@ -64,6 +64,51 @@ export declare const registryAbi: readonly [{
             readonly type: "address";
         }];
     }];
+}, {
+    readonly type: "function";
+    readonly name: "registerAgent";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "metadataURI";
+        readonly type: "string";
+    }, {
+        readonly name: "pricePerTask";
+        readonly type: "uint256";
+    }, {
+        readonly name: "currency";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "updateMetadata";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "newMetadataURI";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "updatePrice";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "newPrice";
+        readonly type: "uint256";
+    }, {
+        readonly name: "currency";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "setActive";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "active";
+        readonly type: "bool";
+    }];
+    readonly outputs: readonly [];
 }];
 export declare const escrowAbi: readonly [{
     readonly type: "function";

package/dist/abis.js

@@ -47,6 +47,42 @@ export const registryAbi = [
             },
         ],
     },
+    // --- Lado del agente: darse de alta y administrarse a sí mismo ---
+    {
+        type: 'function',
+        name: 'registerAgent',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'metadataURI', type: 'string' },
+            { name: 'pricePerTask', type: 'uint256' },
+            { name: 'currency', type: 'address' },
+        ],
+        outputs: [],
+    },
+    {
+        type: 'function',
+        name: 'updateMetadata',
+        stateMutability: 'nonpayable',
+        inputs: [{ name: 'newMetadataURI', type: 'string' }],
+        outputs: [],
+    },
+    {
+        type: 'function',
+        name: 'updatePrice',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'newPrice', type: 'uint256' },
+            { name: 'currency', type: 'address' },
+        ],
+        outputs: [],
+    },
+    {
+        type: 'function',
+        name: 'setActive',
+        stateMutability: 'nonpayable',
+        inputs: [{ name: 'active', type: 'bool' }],
+        outputs: [],
+    },
 ];
 export const escrowAbi = [
     {

package/dist/client.d.ts

@@ -16,8 +16,10 @@
  * y en uso: el caso de "quiero probar esto ahora" no debería exigir un .env.
  */
 import type { Account, Address, Hex, PublicClient } from 'viem';
+import { type AskResult, type X402Accept } from './x402.js';
+import { type CallEnvelope } from './envelope.js';
 import { type PanalAddresses, type PanalNetwork } from './chains.js';
-import { type Agent, type Task } from './types.js';
+import { TaskStatus, type Agent, type AgentMetadata, type Task } from './types.js';
 export interface PanalClientOptions {
     /** `mainnet` por defecto. */
     network?: PanalNetwork;
@@ -97,6 +99,112 @@ export declare class PanalClient {
      * registrada: sin ella el agente no construye reputación.
      */
     approveTask(taskId: bigint, rating: number): Promise<Hex>;
+    /**
+     * Registra tu agente en el marketplace. Lo llama la wallet que trabajará y
+     * cobrará: en Panal el agente ES una dirección, no una fila en una base de
+     * datos de alguien.
+     */
+    registerAgent(params: {
+        metadata: AgentMetadata;
+        pricePerTask: bigint;
+        /** `NATIVE_CURRENCY` (MON) o la dirección de $PANAL. */
+        currency?: Address;
+    }): Promise<Hex>;
+    /** Cambia el nombre, la descripción, las skills o el endpoint publicados. */
+    updateMetadata(metadata: AgentMetadata): Promise<Hex>;
+    /** Cambia el precio por tarea, y opcionalmente la moneda en la que cobras. */
+    updatePrice(pricePerTask: bigint, currency?: Address): Promise<Hex>;
+    /**
+     * Enciende o apaga tu agente. Apagado deja de aparecer en el marketplace y no
+     * acepta encargos nuevos; los que ya tenga siguen su curso. Úsalo antes de
+     * irte de vacaciones: mejor invisible que incumpliendo plazos.
+     */
+    setActive(active: boolean): Promise<Hex>;
+    /**
+     * Entrega el resultado de una tarea. Ancla su keccak256 on-chain; el texto se
+     * queda contigo y se lo sirves al cliente por tu endpoint.
+     *
+     * Devuelve también el hash calculado: guárdalo junto al texto. Si más adelante
+     * sirves algo que no case con él, el cliente lo detectará y con razón.
+     */
+    deliverResult(taskId: bigint, resultText: string): Promise<{
+        txHash: Hex;
+        resultHash: Hex;
+    }>;
+    /**
+     * Las tareas asignadas a una dirección, de la más reciente hacia atrás.
+     *
+     * Recorre el escrow leyendo tarea a tarea en vez de usar `eth_getLogs`: el RPC
+     * público limita los rangos de bloques a ~100, así que un filtro de eventos
+     * solo ve lo de hace un rato. `limit` acota cuántas se revisan.
+     */
+    getTasksFor(worker: Address, options?: {
+        limit?: number;
+        status?: TaskStatus;
+    }): Promise<Task[]>;
+    /**
+     * Pregunta el precio de un agente sin pagar nada.
+     *
+     * Es gratis y no compromete: puedes cotizar a varios candidatos y decidir.
+     */
+    quoteAgent(agent: Address, prompt: string, options?: {
+        allowInsecure?: boolean;
+    }): Promise<X402Accept>;
+    /**
+     * Paga a un agente concreto por una consulta y devuelve su respuesta.
+     *
+     * `maxSpend` es obligatorio: el precio lo pone el otro extremo, así que sin
+     * tope estarías firmando lo que te pidan.
+     */
+    askAgent(agent: Address, prompt: string, options: {
+        maxSpend: bigint;
+        quote?: X402Accept;
+        allowInsecure?: boolean;
+        timeoutMs?: number;
+    }): Promise<AskResult>;
+    /**
+     * Busca un agente con esa skill, negocia el precio y le paga por la consulta.
+     *
+     * Es la operación que hace de Panal algo más que un directorio: una llamada
+     * a función que cruza una frontera económica.
+     *
+     *   const respuesta = await panal.ask('traducción', 'traduce esto', {
+     *     maxSpend: parseEther('0.01'),
+     *   });
+     *
+     * Cotiza a los candidatos —gratis, con el 402— y se queda con el más barato
+     * que quepa en el presupuesto. Los que no cobran por llamada o no responden
+     * se descartan sin ruido: que un agente esté caído no debe tumbar al que
+     * pregunta.
+     */
+    ask(skill: string, prompt: string, options: {
+        maxSpend: bigint;
+        /** Cuántos candidatos se cotizan como mucho. Cada uno es una petición. */
+        maxCandidates?: number;
+        /** Descartar a estos (evita que un agente se llame a sí mismo). */
+        exclude?: Address[];
+        allowInsecure?: boolean;
+        timeoutMs?: number;
+        /**
+         * Sobre recibido, si este agente está atendiendo una llamada de otro.
+         * Sin él se abre una cadena nueva. Con él, se hereda lo que quede de
+         * profundidad y presupuesto, que es lo que impide que A→B→C→A se coma
+         * el dinero dando vueltas.
+         */
+        envelope?: CallEnvelope | null;
+        /** Saltos permitidos al abrir una cadena nueva. */
+        depth?: number;
+    }): Promise<AskResult & {
+        agent: Address;
+    }>;
+    /**
+     * Dónde escucha el x402 de un agente.
+     *
+     * Se prefiere lo que el propio agente anuncia en su `agent.json`; si no lo
+     * anuncia, se prueba la ruta por convención. Así funciona con los agentes que
+     * ya están desplegados sin obligarles a actualizarse.
+     */
+    private x402Endpoint;
     /** Retira lo acreditado en una moneda (patrón pull payment). */
     withdraw(currency?: Address): Promise<Hex>;
     /** Comprueba el saldo antes de firmar, para fallar con un mensaje legible. */

package/dist/client.js

@@ -17,8 +17,11 @@
  */
 import { createPublicClient, createWalletClient, formatEther, getAddress, http, keccak256, toBytes } from 'viem';
 import { erc20Abi, escrowAbi, registryAbi } from './abis.js';
+import { assertPublicUrl, fetchLimited } from './net.js';
+import { X402Error, payAndAsk, quoteAsk } from './x402.js';
+import { descend, newEnvelope, remainingBudget } from './envelope.js';
 import { NATIVE_CURRENCY, addressesFor, chainFor } from './chains.js';
-import { TaskStatus, parseAgentMetadata } from './types.js';
+import { TaskStatus, formatAgentMetadata, parseAgentMetadata, } from './types.js';
 /** Cuántos agentes se leen por llamada al registry. */
 const REGISTRY_PAGE = 50n;
 /** Tope duro de agentes recorridos, por si el registro crece mucho. */
@@ -228,6 +231,254 @@ export class PanalClient {
         await this.publicClient.waitForTransactionReceipt({ hash });
         return hash;
     }
+    // -------------------------------------------------------------------------
+    // Lado del AGENTE — darse de alta, trabajar y entregar.
+    // -------------------------------------------------------------------------
+    /**
+     * Registra tu agente en el marketplace. Lo llama la wallet que trabajará y
+     * cobrará: en Panal el agente ES una dirección, no una fila en una base de
+     * datos de alguien.
+     */
+    async registerAgent(params) {
+        const wallet = this.wallet();
+        const hash = await wallet.writeContract({
+            address: this.addresses.registry,
+            abi: registryAbi,
+            functionName: 'registerAgent',
+            args: [formatAgentMetadata(params.metadata), params.pricePerTask, params.currency ?? NATIVE_CURRENCY],
+            chain: chainFor(this.network),
+            account: this.account,
+        });
+        await this.publicClient.waitForTransactionReceipt({ hash });
+        return hash;
+    }
+    /** Cambia el nombre, la descripción, las skills o el endpoint publicados. */
+    async updateMetadata(metadata) {
+        const wallet = this.wallet();
+        const hash = await wallet.writeContract({
+            address: this.addresses.registry,
+            abi: registryAbi,
+            functionName: 'updateMetadata',
+            args: [formatAgentMetadata(metadata)],
+            chain: chainFor(this.network),
+            account: this.account,
+        });
+        await this.publicClient.waitForTransactionReceipt({ hash });
+        return hash;
+    }
+    /** Cambia el precio por tarea, y opcionalmente la moneda en la que cobras. */
+    async updatePrice(pricePerTask, currency = NATIVE_CURRENCY) {
+        const wallet = this.wallet();
+        const hash = await wallet.writeContract({
+            address: this.addresses.registry,
+            abi: registryAbi,
+            functionName: 'updatePrice',
+            args: [pricePerTask, currency],
+            chain: chainFor(this.network),
+            account: this.account,
+        });
+        await this.publicClient.waitForTransactionReceipt({ hash });
+        return hash;
+    }
+    /**
+     * Enciende o apaga tu agente. Apagado deja de aparecer en el marketplace y no
+     * acepta encargos nuevos; los que ya tenga siguen su curso. Úsalo antes de
+     * irte de vacaciones: mejor invisible que incumpliendo plazos.
+     */
+    async setActive(active) {
+        const wallet = this.wallet();
+        const hash = await wallet.writeContract({
+            address: this.addresses.registry,
+            abi: registryAbi,
+            functionName: 'setActive',
+            args: [active],
+            chain: chainFor(this.network),
+            account: this.account,
+        });
+        await this.publicClient.waitForTransactionReceipt({ hash });
+        return hash;
+    }
+    /**
+     * Entrega el resultado de una tarea. Ancla su keccak256 on-chain; el texto se
+     * queda contigo y se lo sirves al cliente por tu endpoint.
+     *
+     * Devuelve también el hash calculado: guárdalo junto al texto. Si más adelante
+     * sirves algo que no case con él, el cliente lo detectará y con razón.
+     */
+    async deliverResult(taskId, resultText) {
+        const wallet = this.wallet();
+        const task = await this.getTask(taskId);
+        if (task.worker.toLowerCase() !== this.account.address.toLowerCase()) {
+            throw new Error(`La tarea #${taskId} está asignada a ${task.worker}, no a ti.`);
+        }
+        if (task.status !== TaskStatus.Open) {
+            throw new Error(`La tarea #${taskId} está "${TaskStatus[task.status]}": solo se entrega lo que sigue abierto.`);
+        }
+        const resultHash = keccak256(toBytes(resultText));
+        const txHash = await wallet.writeContract({
+            address: this.addresses.escrow,
+            abi: escrowAbi,
+            functionName: 'deliverResult',
+            args: [taskId, resultHash],
+            chain: chainFor(this.network),
+            account: this.account,
+        });
+        await this.publicClient.waitForTransactionReceipt({ hash: txHash });
+        return { txHash, resultHash };
+    }
+    /**
+     * Las tareas asignadas a una dirección, de la más reciente hacia atrás.
+     *
+     * Recorre el escrow leyendo tarea a tarea en vez de usar `eth_getLogs`: el RPC
+     * público limita los rangos de bloques a ~100, así que un filtro de eventos
+     * solo ve lo de hace un rato. `limit` acota cuántas se revisan.
+     */
+    async getTasksFor(worker, options = {}) {
+        const count = await this.getTaskCount();
+        const limit = options.limit ?? 50;
+        const target = getAddress(worker).toLowerCase();
+        const found = [];
+        for (let id = count - 1n; id >= 0n && found.length < limit; id--) {
+            const task = await this.getTask(id);
+            if (task.worker.toLowerCase() !== target)
+                continue;
+            if (options.status !== undefined && task.status !== options.status)
+                continue;
+            found.push(task);
+            if (id === 0n)
+                break;
+        }
+        return found;
+    }
+    // -------------------------------------------------------------------------
+    // Llamar a otro agente y pagarle al momento (x402).
+    //
+    // Esto es lo que permite que un agente contrate a otro sin humano de por
+    // medio. A diferencia del escrow, aquí no hay tarea, ni plazo, ni disputa:
+    // se paga y se responde en la misma llamada. Por eso vale para consultas de
+    // céntimos y NO vale para un encargo serio.
+    // -------------------------------------------------------------------------
+    /**
+     * Pregunta el precio de un agente sin pagar nada.
+     *
+     * Es gratis y no compromete: puedes cotizar a varios candidatos y decidir.
+     */
+    async quoteAgent(agent, prompt, options = {}) {
+        const endpoint = await this.x402Endpoint(agent, options);
+        return quoteAsk(endpoint, prompt, { payer: this.account?.address, ...options });
+    }
+    /**
+     * Paga a un agente concreto por una consulta y devuelve su respuesta.
+     *
+     * `maxSpend` es obligatorio: el precio lo pone el otro extremo, así que sin
+     * tope estarías firmando lo que te pidan.
+     */
+    async askAgent(agent, prompt, options) {
+        const wallet = this.wallet();
+        const endpoint = await this.x402Endpoint(agent, options);
+        return payAndAsk(wallet, this.account, endpoint, prompt, {
+            ...options,
+            chainId: chainFor(this.network).id,
+            // Se ata a quién esperamos pagar: si el endpoint estuviera secuestrado y
+            // cotizara a nombre de otro, la firma no llega a producirse.
+            expectedPayee: agent,
+        });
+    }
+    /**
+     * Busca un agente con esa skill, negocia el precio y le paga por la consulta.
+     *
+     * Es la operación que hace de Panal algo más que un directorio: una llamada
+     * a función que cruza una frontera económica.
+     *
+     *   const respuesta = await panal.ask('traducción', 'traduce esto', {
+     *     maxSpend: parseEther('0.01'),
+     *   });
+     *
+     * Cotiza a los candidatos —gratis, con el 402— y se queda con el más barato
+     * que quepa en el presupuesto. Los que no cobran por llamada o no responden
+     * se descartan sin ruido: que un agente esté caído no debe tumbar al que
+     * pregunta.
+     */
+    async ask(skill, prompt, options) {
+        const wallet = this.wallet();
+        const excluded = new Set([...(options.exclude ?? []), this.account.address].map((a) => getAddress(a).toLowerCase()));
+        // El presupuesto real es el menor entre lo que dice el sobre y el tope de
+        // esta llamada: heredar una cadena no puede ampliar lo que autorizaste.
+        const heredado = options.envelope ?? newEnvelope({ budget: options.maxSpend, depth: options.depth });
+        const tope = remainingBudget(options.envelope ?? null, options.maxSpend);
+        if (tope <= 0n)
+            throw new X402Error('El presupuesto de la cadena está agotado: no se puede delegar más.');
+        const candidates = (await this.searchAgents(skill))
+            .filter((a) => !excluded.has(a.address.toLowerCase()) && a.metadata.botUrl)
+            .slice(0, options.maxCandidates ?? 5);
+        if (!candidates.length)
+            throw new X402Error(`Ningún agente activo con la skill "${skill}" publica endpoint.`);
+        const quotes = [];
+        const rechazos = [];
+        for (const agent of candidates) {
+            try {
+                const endpoint = await this.x402Endpoint(agent.address, options, agent);
+                const accept = await quoteAsk(endpoint, prompt, {
+                    payer: this.account.address,
+                    ...options,
+                    envelope: heredado,
+                });
+                if (BigInt(accept.amount) <= tope)
+                    quotes.push({ agent, endpoint, accept });
+                else
+                    rechazos.push(`${agent.metadata.name || agent.address}: pide ${accept.amount}, por encima del tope`);
+            }
+            catch (err) {
+                rechazos.push(`${agent.metadata.name || agent.address}: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        if (!quotes.length) {
+            throw new X402Error(`Ningún agente de "${skill}" pudo cotizar dentro del presupuesto.\n  ${rechazos.join('\n  ')}`);
+        }
+        quotes.sort((a, b) => (BigInt(a.accept.amount) < BigInt(b.accept.amount) ? -1 : 1));
+        const elegido = quotes[0];
+        // Se desciende el sobre ANTES de firmar: aquí es donde se comprueba que
+        // quedan saltos, que hay presupuesto y que no estamos cerrando un ciclo.
+        const siguiente = descend(heredado, this.account.address, BigInt(elegido.accept.amount));
+        const result = await payAndAsk(wallet, this.account, elegido.endpoint, prompt, {
+            ...options,
+            maxSpend: tope,
+            chainId: chainFor(this.network).id,
+            expectedPayee: elegido.agent.address,
+            quote: elegido.accept,
+            envelope: siguiente,
+        });
+        return { ...result, agent: elegido.agent.address };
+    }
+    /**
+     * Dónde escucha el x402 de un agente.
+     *
+     * Se prefiere lo que el propio agente anuncia en su `agent.json`; si no lo
+     * anuncia, se prueba la ruta por convención. Así funciona con los agentes que
+     * ya están desplegados sin obligarles a actualizarse.
+     */
+    async x402Endpoint(agent, options = {}, known) {
+        const info = known ?? (await this.getAgent(agent));
+        const base = info.metadata.botUrl;
+        if (!base)
+            throw new X402Error(`El agente ${agent} no publica endpoint en su metadata.`);
+        try {
+            const url = await assertPublicUrl(new URL('/agent.json', base).toString(), options);
+            const res = await fetchLimited(url, { timeoutMs: 10_000 });
+            if (res.status === 200) {
+                const card = JSON.parse(res.text);
+                const anunciado = card.endpoints?.x402Ask;
+                if (anunciado?.url)
+                    return anunciado.url;
+                if (anunciado?.path)
+                    return new URL(anunciado.path, base).toString();
+            }
+        }
+        catch {
+            /* sin tarjeta o ilegible: se cae a la convención */
+        }
+        return new URL('/x402/ask', base).toString();
+    }
     /** Retira lo acreditado en una moneda (patrón pull payment). */
     async withdraw(currency = NATIVE_CURRENCY) {
         const wallet = this.wallet();

package/dist/envelope.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Panal SDK — el sobre que viaja con una llamada entre agentes.
+ *
+ * Cuando un agente puede llamar a otro, y ese a otro, aparecen tres problemas
+ * que no existen en una llamada suelta:
+ *
+ *   1. CICLOS. A llama a B, B a C y C a A. Bucle infinito, y aquí cada vuelta
+ *      cuesta dinero de verdad.
+ *   2. PROFUNDIDAD. Sin tope, una cadena se alarga sola y el que empezó paga
+ *      saltos que nunca autorizó.
+ *   3. PRESUPUESTO. Si A tiene 0.01 para gastar y B subcontrata por 0.05, ¿quién
+ *      lo paga? Sin un límite que viaje con la llamada, nadie sabe cuánto queda.
+ *
+ * El sobre resuelve los tres con cuatro cabeceras que se propagan hop a hop,
+ * como un trace distribuido pero con dinero dentro:
+ *
+ *   X-Panal-Trace:  id de la cadena entera, para poder seguirla en los logs
+ *   X-Panal-Depth:  saltos que QUEDAN. Cada agente lo decrementa al delegar
+ *   X-Panal-Budget: wei disponibles para sub-llamadas, menos lo ya gastado
+ *   X-Panal-Path:   por dónde ha pasado ya, para detectar el ciclo
+ *
+ * Es deliberadamente sin estado: todo va en la petición. Un agente que se
+ * reinicia no pierde la protección, y no hace falta coordinar nada entre ellos.
+ *
+ * Sobre la confianza: un intermediario malicioso podría borrarse del `path` para
+ * provocar un bucle. Puede, pero el bucle lo paga él —cada salto lo abona quien
+ * llama—, así que el incentivo va en contra. El sobre protege de cadenas
+ * accidentales y de agentes mal escritos, que es de lo que hay que protegerse.
+ */
+import type { Address } from 'viem';
+export declare const ENVELOPE_HEADERS: {
+    readonly trace: "x-panal-trace";
+    readonly depth: "x-panal-depth";
+    readonly budget: "x-panal-budget";
+    readonly path: "x-panal-path";
+};
+/** Saltos por defecto si quien empieza la cadena no dice otra cosa. */
+export declare const DEFAULT_DEPTH = 3;
+/** Tope duro: ni aunque lo pidan. Acota el coste máximo de una cadena. */
+export declare const MAX_DEPTH = 8;
+export interface CallEnvelope {
+    /** Identifica la cadena entera. Solo sirve para seguirla en los logs. */
+    trace: string;
+    /** Saltos que quedan. 0 = este agente resuelve solo, sin delegar. */
+    depth: number;
+    /** Unidades mínimas disponibles para sub-llamadas. */
+    budget: bigint;
+    /** Agentes que ya han atendido esta cadena, en orden. */
+    path: Address[];
+}
+export declare class LoopDetected extends Error {
+    readonly me: Address;
+    readonly trace: string;
+    constructor(me: Address, trace: string);
+}
+export declare class DepthExhausted extends Error {
+    readonly trace: string;
+    constructor(trace: string);
+}
+export declare class BudgetExhausted extends Error {
+    readonly available: bigint;
+    readonly needed: bigint;
+    constructor(available: bigint, needed: bigint);
+}
+/** Abre una cadena nueva. Lo llama quien la empieza, no un intermediario. */
+export declare function newEnvelope(params: {
+    budget: bigint;
+    depth?: number;
+    trace?: string;
+}): CallEnvelope;
+/** Las cabeceras a poner en la petición saliente. */
+export declare function envelopeHeaders(env: CallEnvelope): Record<string, string>;
+/**
+ * Lee el sobre de una petición entrante. Devuelve null si no viene ninguno —una
+ * llamada suelta de un humano, por ejemplo—, que es un caso legítimo.
+ *
+ * Nunca lanza: las cabeceras las escribe quien llama, o sea un desconocido, así
+ * que todo se sanea en vez de confiar. Un `depth` de un millón se recorta al
+ * tope y un path descomunal se trunca.
+ */
+export declare function parseEnvelope(headers: Record<string, string | string[] | undefined> | Headers): CallEnvelope | null;
+/**
+ * Comprueba, del lado del SERVIDOR, que se puede atender esta llamada.
+ *
+ * Se llama nada más recibir la petición y antes de trabajar: si es un ciclo,
+ * responder costaría dinero a alguien para nada. El código HTTP correcto para
+ * rechazarla es 508 Loop Detected.
+ */
+export declare function assertCanServe(env: CallEnvelope | null, me: Address): void;
+/**
+ * Prepara el sobre para el SIGUIENTE salto, del lado del CLIENTE.
+ *
+ * Lo llama un agente justo antes de delegar: se añade al path, gasta un salto y
+ * descuenta lo que va a pagar. Lanza si no queda profundidad o presupuesto, así
+ * que el límite se aplica antes de firmar nada.
+ */
+export declare function descend(env: CallEnvelope, me: Address, willSpend: bigint): CallEnvelope;
+/** Cuánto puede gastar este agente en sub-llamadas, según el sobre. */
+export declare function remainingBudget(env: CallEnvelope | null, fallback: bigint): bigint;

package/dist/envelope.js

@@ -0,0 +1,188 @@
+/**
+ * Panal SDK — el sobre que viaja con una llamada entre agentes.
+ *
+ * Cuando un agente puede llamar a otro, y ese a otro, aparecen tres problemas
+ * que no existen en una llamada suelta:
+ *
+ *   1. CICLOS. A llama a B, B a C y C a A. Bucle infinito, y aquí cada vuelta
+ *      cuesta dinero de verdad.
+ *   2. PROFUNDIDAD. Sin tope, una cadena se alarga sola y el que empezó paga
+ *      saltos que nunca autorizó.
+ *   3. PRESUPUESTO. Si A tiene 0.01 para gastar y B subcontrata por 0.05, ¿quién
+ *      lo paga? Sin un límite que viaje con la llamada, nadie sabe cuánto queda.
+ *
+ * El sobre resuelve los tres con cuatro cabeceras que se propagan hop a hop,
+ * como un trace distribuido pero con dinero dentro:
+ *
+ *   X-Panal-Trace:  id de la cadena entera, para poder seguirla en los logs
+ *   X-Panal-Depth:  saltos que QUEDAN. Cada agente lo decrementa al delegar
+ *   X-Panal-Budget: wei disponibles para sub-llamadas, menos lo ya gastado
+ *   X-Panal-Path:   por dónde ha pasado ya, para detectar el ciclo
+ *
+ * Es deliberadamente sin estado: todo va en la petición. Un agente que se
+ * reinicia no pierde la protección, y no hace falta coordinar nada entre ellos.
+ *
+ * Sobre la confianza: un intermediario malicioso podría borrarse del `path` para
+ * provocar un bucle. Puede, pero el bucle lo paga él —cada salto lo abona quien
+ * llama—, así que el incentivo va en contra. El sobre protege de cadenas
+ * accidentales y de agentes mal escritos, que es de lo que hay que protegerse.
+ */
+import { getAddress, isAddress } from 'viem';
+export const ENVELOPE_HEADERS = {
+    trace: 'x-panal-trace',
+    depth: 'x-panal-depth',
+    budget: 'x-panal-budget',
+    path: 'x-panal-path',
+};
+/** Saltos por defecto si quien empieza la cadena no dice otra cosa. */
+export const DEFAULT_DEPTH = 3;
+/** Tope duro: ni aunque lo pidan. Acota el coste máximo de una cadena. */
+export const MAX_DEPTH = 8;
+/** Tope de direcciones en el path, por si llega una cabecera enorme. */
+const MAX_PATH = 16;
+export class LoopDetected extends Error {
+    me;
+    trace;
+    constructor(me, trace) {
+        super(`Ciclo detectado: ${me} ya atendió la cadena ${trace}. Se rechaza para no pagarla dos veces.`);
+        this.me = me;
+        this.trace = trace;
+        this.name = 'LoopDetected';
+    }
+}
+export class DepthExhausted extends Error {
+    trace;
+    constructor(trace) {
+        super(`Sin saltos disponibles en la cadena ${trace}: hay que resolver sin delegar.`);
+        this.trace = trace;
+        this.name = 'DepthExhausted';
+    }
+}
+export class BudgetExhausted extends Error {
+    available;
+    needed;
+    constructor(available, needed) {
+        super(`El presupuesto que queda (${available}) no cubre ${needed}.`);
+        this.available = available;
+        this.needed = needed;
+        this.name = 'BudgetExhausted';
+    }
+}
+/** Abre una cadena nueva. Lo llama quien la empieza, no un intermediario. */
+export function newEnvelope(params) {
+    return {
+        trace: params.trace ?? randomTrace(),
+        depth: clampDepth(params.depth ?? DEFAULT_DEPTH),
+        budget: params.budget < 0n ? 0n : params.budget,
+        path: [],
+    };
+}
+/** Las cabeceras a poner en la petición saliente. */
+export function envelopeHeaders(env) {
+    return {
+        [ENVELOPE_HEADERS.trace]: env.trace,
+        [ENVELOPE_HEADERS.depth]: String(env.depth),
+        [ENVELOPE_HEADERS.budget]: env.budget.toString(),
+        [ENVELOPE_HEADERS.path]: env.path.join(','),
+    };
+}
+/**
+ * Lee el sobre de una petición entrante. Devuelve null si no viene ninguno —una
+ * llamada suelta de un humano, por ejemplo—, que es un caso legítimo.
+ *
+ * Nunca lanza: las cabeceras las escribe quien llama, o sea un desconocido, así
+ * que todo se sanea en vez de confiar. Un `depth` de un millón se recorta al
+ * tope y un path descomunal se trunca.
+ */
+export function parseEnvelope(headers) {
+    const get = (name) => {
+        if (typeof headers.get === 'function')
+            return headers.get(name) ?? undefined;
+        const raw = headers[name];
+        return Array.isArray(raw) ? raw[0] : raw;
+    };
+    const trace = get(ENVELOPE_HEADERS.trace)?.trim();
+    if (!trace)
+        return null;
+    let depth = Number.parseInt(get(ENVELOPE_HEADERS.depth) ?? '', 10);
+    if (!Number.isFinite(depth))
+        depth = 0;
+    let budget = 0n;
+    try {
+        const raw = get(ENVELOPE_HEADERS.budget)?.trim();
+        if (raw)
+            budget = BigInt(raw);
+    }
+    catch {
+        budget = 0n; // ilegible = sin presupuesto, que es el lado seguro
+    }
+    const path = (get(ENVELOPE_HEADERS.path) ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        // `strict: false`: sin esto viem exige checksum y una direccion en
+        // minusculas —perfectamente valida, y lo que manda cualquier otra
+        // implementacion— se descartaria en silencio. El ciclo dejaria de
+        // detectarse justo con los agentes que no son nuestros.
+        .filter((s) => isAddress(s, { strict: false }))
+        .slice(0, MAX_PATH)
+        .map((s) => getAddress(s));
+    return {
+        trace: trace.slice(0, 128),
+        depth: clampDepth(depth),
+        budget: budget < 0n ? 0n : budget,
+        path,
+    };
+}
+/**
+ * Comprueba, del lado del SERVIDOR, que se puede atender esta llamada.
+ *
+ * Se llama nada más recibir la petición y antes de trabajar: si es un ciclo,
+ * responder costaría dinero a alguien para nada. El código HTTP correcto para
+ * rechazarla es 508 Loop Detected.
+ */
+export function assertCanServe(env, me) {
+    if (!env)
+        return; // sin sobre no hay cadena que vigilar
+    const yo = getAddress(me);
+    if (env.path.some((a) => getAddress(a) === yo))
+        throw new LoopDetected(yo, env.trace);
+}
+/**
+ * Prepara el sobre para el SIGUIENTE salto, del lado del CLIENTE.
+ *
+ * Lo llama un agente justo antes de delegar: se añade al path, gasta un salto y
+ * descuenta lo que va a pagar. Lanza si no queda profundidad o presupuesto, así
+ * que el límite se aplica antes de firmar nada.
+ */
+export function descend(env, me, willSpend) {
+    if (env.depth <= 0)
+        throw new DepthExhausted(env.trace);
+    if (willSpend > env.budget)
+        throw new BudgetExhausted(env.budget, willSpend);
+    const yo = getAddress(me);
+    if (env.path.some((a) => getAddress(a) === yo))
+        throw new LoopDetected(yo, env.trace);
+    return {
+        trace: env.trace,
+        depth: env.depth - 1,
+        budget: env.budget - willSpend,
+        path: [...env.path, yo].slice(-MAX_PATH),
+    };
+}
+/** Cuánto puede gastar este agente en sub-llamadas, según el sobre. */
+export function remainingBudget(env, fallback) {
+    if (!env)
+        return fallback;
+    return env.budget < fallback ? env.budget : fallback;
+}
+function clampDepth(depth) {
+    if (!Number.isFinite(depth) || depth < 0)
+        return 0;
+    return Math.min(Math.floor(depth), MAX_DEPTH);
+}
+function randomTrace() {
+    const g = globalThis;
+    if (typeof g.crypto?.randomUUID === 'function')
+        return g.crypto.randomUUID();
+    return `panal-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}

package/dist/index.d.ts

@@ -26,3 +26,9 @@ export type { PanalNetwork, PanalAddresses } from './chains.js';
 export { TaskStatus, TASK_STATUS_LABEL, formatAgentMetadata, parseAgentMetadata, } from './types.js';
 export type { Agent, AgentMetadata, Task } from './types.js';
 export { erc20Abi, escrowAbi, registryAbi } from './abis.js';
+export { X402_SCHEME, X402Error, payAndAsk, quoteAsk } from './x402.js';
+export type { AskResult, PayAndAskOptions, PermitDomain, X402Accept, X402Quote } from './x402.js';
+export { assertPublicUrl, fetchLimited, isPrivateIp } from './net.js';
+export { ENVELOPE_HEADERS, DEFAULT_DEPTH, MAX_DEPTH, BudgetExhausted, DepthExhausted, LoopDetected, assertCanServe, descend, envelopeHeaders, newEnvelope, parseEnvelope, remainingBudget, } from './envelope.js';
+export type { CallEnvelope } from './envelope.js';
+export type { UrlGuardOptions } from './net.js';

package/dist/index.js

@@ -23,3 +23,8 @@ export { PanalClient, createPanalClient } from './client.js';
 export { monad, monadTestnet, addressesFor, chainFor, MAINNET_ADDRESSES, TESTNET_ADDRESSES, NATIVE_CURRENCY, FEE_BPS, AUTO_RELEASE_SECONDS, DISPUTE_TIMEOUT_SECONDS, } from './chains.js';
 export { TaskStatus, TASK_STATUS_LABEL, formatAgentMetadata, parseAgentMetadata, } from './types.js';
 export { erc20Abi, escrowAbi, registryAbi } from './abis.js';
+// x402: pagar a otro agente por una consulta, sin escrow y sin humano.
+export { X402_SCHEME, X402Error, payAndAsk, quoteAsk } from './x402.js';
+export { assertPublicUrl, fetchLimited, isPrivateIp } from './net.js';
+// El sobre que viaja entre agentes: profundidad, presupuesto y detección de ciclos.
+export { ENVELOPE_HEADERS, DEFAULT_DEPTH, MAX_DEPTH, BudgetExhausted, DepthExhausted, LoopDetected, assertCanServe, descend, envelopeHeaders, newEnvelope, parseEnvelope, remainingBudget, } from './envelope.js';

package/dist/net.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Panal SDK — validación de las URLs de otros agentes.
+ *
+ * El endpoint de un agente sale de su metadata on-chain, así que lo escribe un
+ * desconocido. Cualquiera puede registrarse con
+ * `bot:http://169.254.169.254/latest/meta-data/` y usar tu agente para leer las
+ * credenciales de la máquina donde corre. Por eso toda URL ajena pasa por aquí
+ * antes de que se le pida nada.
+ *
+ * Funciona en Node y en el navegador. En Node resuelve el DNS para cazar un
+ * dominio que apunte a una IP interna; en el navegador no hay DNS accesible, se
+ * queda en la validación de la URL, y tampoco importa tanto: ahí el riesgo de
+ * alcanzar la red privada de un servidor no existe.
+ */
+/** ¿Esta IP apunta dentro de una red privada o reservada? */
+export declare function isPrivateIp(ip: string): boolean;
+export interface UrlGuardOptions {
+    /**
+     * Permitir http:// y direcciones privadas. SOLO para desarrollo local: la
+     * petición lleva una firma tuya, y en claro la lee cualquiera por el camino.
+     */
+    allowInsecure?: boolean;
+}
+/**
+ * Devuelve la URL si es segura de visitar, o lanza explicando por qué no.
+ *
+ * Queda una ventana de DNS rebinding —se resuelve aquí y `fetch` vuelve a
+ * resolver por su cuenta—. Cerrarla del todo exige un agente HTTP a medida; el
+ * riesgo residual es aceptable porque la respuesta nunca se ejecuta.
+ */
+export declare function assertPublicUrl(raw: string, options?: UrlGuardOptions): Promise<URL>;
+/**
+ * `fetch` con tope de tamaño y de tiempo. La respuesta viene de un servidor
+ * ajeno: sin tope, uno hostil se lleva por delante el proceso.
+ */
+export declare function fetchLimited(url: URL | string, init?: RequestInit & {
+    maxBytes?: number;
+    timeoutMs?: number;
+}): Promise<{
+    status: number;
+    headers: Headers;
+    text: string;
+}>;

package/dist/net.js

@@ -0,0 +1,142 @@
+/**
+ * Panal SDK — validación de las URLs de otros agentes.
+ *
+ * El endpoint de un agente sale de su metadata on-chain, así que lo escribe un
+ * desconocido. Cualquiera puede registrarse con
+ * `bot:http://169.254.169.254/latest/meta-data/` y usar tu agente para leer las
+ * credenciales de la máquina donde corre. Por eso toda URL ajena pasa por aquí
+ * antes de que se le pida nada.
+ *
+ * Funciona en Node y en el navegador. En Node resuelve el DNS para cazar un
+ * dominio que apunte a una IP interna; en el navegador no hay DNS accesible, se
+ * queda en la validación de la URL, y tampoco importa tanto: ahí el riesgo de
+ * alcanzar la red privada de un servidor no existe.
+ */
+/** ¿Esta IP apunta dentro de una red privada o reservada? */
+export function isPrivateIp(ip) {
+    const v6 = ip.toLowerCase();
+    if (v6.includes(':')) {
+        if (v6 === '::1' || v6 === '::')
+            return true;
+        if (/^f[cd]/.test(v6) || v6.startsWith('fe80'))
+            return true;
+        const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(v6);
+        return mapped ? isPrivateIp(mapped[1]) : false;
+    }
+    const parts = ip.split('.').map(Number);
+    if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+        return false;
+    const [a = 0, b = 0] = parts;
+    return (a === 0 ||
+        a === 10 ||
+        a === 127 ||
+        (a === 169 && b === 254) || // metadatos de la nube: credenciales
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 100 && b >= 64 && b <= 127) || // CGNAT
+        a >= 224 // multicast y reservadas
+    );
+}
+const LOCAL_NAMES = /^(localhost|.*\.local|.*\.internal|.*\.localhost)$/i;
+/**
+ * Devuelve la URL si es segura de visitar, o lanza explicando por qué no.
+ *
+ * Queda una ventana de DNS rebinding —se resuelve aquí y `fetch` vuelve a
+ * resolver por su cuenta—. Cerrarla del todo exige un agente HTTP a medida; el
+ * riesgo residual es aceptable porque la respuesta nunca se ejecuta.
+ */
+export async function assertPublicUrl(raw, options = {}) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`No es una URL válida: ${raw}`);
+    }
+    if (url.username || url.password)
+        throw new Error('La URL lleva credenciales embebidas: se rechaza.');
+    if (url.protocol !== 'https:' && !(options.allowInsecure && url.protocol === 'http:')) {
+        throw new Error(`El endpoint tiene que ser https y es ${url.protocol}//`);
+    }
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    if (options.allowInsecure)
+        return url;
+    if (LOCAL_NAMES.test(host))
+        throw new Error(`La URL apunta a un nombre local (${host}): se rechaza.`);
+    // Si el host YA es una IP, se comprueba directamente y no hace falta DNS.
+    const isLiteralIp = /^[\d.]+$/.test(host) || host.includes(':');
+    if (isLiteralIp) {
+        if (isPrivateIp(host))
+            throw new Error(`La URL apunta a una dirección interna (${host}): se rechaza.`);
+        return url;
+    }
+    // Resolución DNS solo donde exista. En el navegador se omite a propósito.
+    const lookup = await loadDnsLookup();
+    if (!lookup)
+        return url;
+    let addresses;
+    try {
+        addresses = (await lookup(host, { all: true })).map((r) => r.address);
+    }
+    catch {
+        throw new Error(`No se pudo resolver ${host}.`);
+    }
+    if (!addresses.length)
+        throw new Error(`${host} no resuelve a ninguna dirección.`);
+    for (const ip of addresses) {
+        if (isPrivateIp(ip))
+            throw new Error(`${host} resuelve a una dirección interna (${ip}): se rechaza.`);
+    }
+    return url;
+}
+/** Carga node:dns si estamos en Node; devuelve null en el navegador. */
+async function loadDnsLookup() {
+    try {
+        // El import va en una variable para que los empaquetadores de navegador no
+        // intenten resolver 'node:dns' de forma estática y fallen al construir.
+        const mod = 'node:dns/promises';
+        const dns = (await import(/* @vite-ignore */ mod));
+        return typeof dns.lookup === 'function' ? dns.lookup : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `fetch` con tope de tamaño y de tiempo. La respuesta viene de un servidor
+ * ajeno: sin tope, uno hostil se lleva por delante el proceso.
+ */
+export async function fetchLimited(url, init = {}) {
+    const { maxBytes = 512 * 1024, timeoutMs = 30_000, ...rest } = init;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { ...rest, signal: controller.signal });
+        const reader = res.body?.getReader();
+        if (!reader)
+            return { status: res.status, headers: res.headers, text: '' };
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel();
+                throw new Error(`La respuesta pasa de ${Math.round(maxBytes / 1024)} KB: se corta.`);
+            }
+            chunks.push(value);
+        }
+        const merged = new Uint8Array(total);
+        let offset = 0;
+        for (const c of chunks) {
+            merged.set(c, offset);
+            offset += c.byteLength;
+        }
+        return { status: res.status, headers: res.headers, text: new TextDecoder().decode(merged) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/x402.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Panal SDK — el lado CLIENTE de x402: pagar a otro agente por una consulta.
+ *
+ * El bot tenía solo la mitad servidor: sabía cobrar, no pagar. Sin esta mitad,
+ * un agente no podía llamar a otro y liquidar al momento, que es lo que hace
+ * falta para que se contraten entre ellos sin un humano por medio.
+ *
+ * El flujo son dos peticiones HTTP:
+ *
+ *   1. POST sin cabecera de pago  → 402 con la cotización (gratis, no compromete
+ *      a nada). Es la propiedad más útil del protocolo: se puede preguntar el
+ *      precio a varios candidatos sin gastar un céntimo.
+ *   2. Se firma un `permit` EIP-2612 y se repite el POST con `X-Payment`. El
+ *      agente cobra, trabaja y responde en la misma llamada.
+ *
+ * El cliente NO paga gas: solo firma. La transacción la manda quien cobra.
+ */
+import type { Account, Address, Hex, WalletClient } from 'viem';
+import { type UrlGuardOptions } from './net.js';
+import { type CallEnvelope } from './envelope.js';
+/** El único esquema que entiende este cliente. Debe coincidir con el servidor. */
+export declare const X402_SCHEME = "eip2612-permit";
+export interface PermitDomain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: Address;
+}
+/** Una forma de pago aceptada, tal y como la publica el 402. */
+export interface X402Accept {
+    scheme: string;
+    network?: string;
+    chainId: number;
+    asset: Address;
+    assetSymbol?: string;
+    amount: string;
+    payTo: Address;
+    resource?: string;
+    description?: string;
+    deadline: number;
+    maxTimeoutSeconds?: number;
+    payerNonce?: string;
+    domain: PermitDomain;
+}
+export interface X402Quote {
+    x402Version?: number;
+    accepts: X402Accept[];
+    hint?: string;
+}
+export declare class X402Error extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/**
+ * Pide la cotización de un endpoint SIN pagar.
+ *
+ * @param payer Si se indica, el servidor devuelve además el nonce del pagador y
+ *              nos ahorramos una lectura de la cadena.
+ */
+export declare function quoteAsk(endpoint: string, prompt: string, options?: {
+    payer?: Address;
+    timeoutMs?: number;
+    envelope?: CallEnvelope;
+} & UrlGuardOptions): Promise<X402Accept>;
+export interface PayAndAskOptions extends UrlGuardOptions {
+    /**
+     * Tope de gasto para esta llamada, en unidades mínimas. OBLIGATORIO: el
+     * precio lo pone el otro extremo, así que sin tope estarías firmando lo que
+     * te pidan.
+     */
+    maxSpend: bigint;
+    /** Cadena esperada. Si la cotización dice otra, se aborta. */
+    chainId: number;
+    /** Token esperado. Si la cotización pide otro, se aborta. */
+    asset?: Address;
+    /** Dirección que debe cobrar. Si no coincide con `payTo`, se aborta. */
+    expectedPayee?: Address;
+    /** Cotización ya obtenida, para no pedirla dos veces. */
+    quote?: X402Accept;
+    timeoutMs?: number;
+    /**
+     * Sobre de la cadena. Va ya descendido: quien llama se ha añadido al path y
+     * ha gastado su salto. Ver `descend()` en envelope.ts.
+     */
+    envelope?: CallEnvelope;
+}
+export interface AskResult {
+    answer: string;
+    /** Lo que se ha pagado de verdad, en unidades mínimas. */
+    paid: bigint;
+    /** Quién ha cobrado. */
+    payee: Address;
+    /** Transacción del cobro, si el servidor la reporta. */
+    txHash?: Hex;
+    endpoint: string;
+}
+/**
+ * Paga una consulta a un endpoint x402 y devuelve la respuesta.
+ *
+ * Todas las comprobaciones van ANTES de firmar. Una firma de permit es una
+ * autorización para llevarse tu saldo: si se valida después, ya es tarde.
+ */
+export declare function payAndAsk(wallet: WalletClient, account: Account, endpoint: string, prompt: string, options: PayAndAskOptions): Promise<AskResult>;

package/dist/x402.js

@@ -0,0 +1,195 @@
+/**
+ * Panal SDK — el lado CLIENTE de x402: pagar a otro agente por una consulta.
+ *
+ * El bot tenía solo la mitad servidor: sabía cobrar, no pagar. Sin esta mitad,
+ * un agente no podía llamar a otro y liquidar al momento, que es lo que hace
+ * falta para que se contraten entre ellos sin un humano por medio.
+ *
+ * El flujo son dos peticiones HTTP:
+ *
+ *   1. POST sin cabecera de pago  → 402 con la cotización (gratis, no compromete
+ *      a nada). Es la propiedad más útil del protocolo: se puede preguntar el
+ *      precio a varios candidatos sin gastar un céntimo.
+ *   2. Se firma un `permit` EIP-2612 y se repite el POST con `X-Payment`. El
+ *      agente cobra, trabaja y responde en la misma llamada.
+ *
+ * El cliente NO paga gas: solo firma. La transacción la manda quien cobra.
+ */
+import { isAddress, getAddress } from 'viem';
+import { assertPublicUrl, fetchLimited } from './net.js';
+import { envelopeHeaders } from './envelope.js';
+/** El único esquema que entiende este cliente. Debe coincidir con el servidor. */
+export const X402_SCHEME = 'eip2612-permit';
+const PERMIT_TYPES = {
+    Permit: [
+        { name: 'owner', type: 'address' },
+        { name: 'spender', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'nonce', type: 'uint256' },
+        { name: 'deadline', type: 'uint256' },
+    ],
+};
+export class X402Error extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'X402Error';
+    }
+}
+/**
+ * Pide la cotización de un endpoint SIN pagar.
+ *
+ * @param payer Si se indica, el servidor devuelve además el nonce del pagador y
+ *              nos ahorramos una lectura de la cadena.
+ */
+export async function quoteAsk(endpoint, prompt, options = {}) {
+    const url = await assertPublicUrl(endpoint, options);
+    const headers = { 'content-type': 'application/json' };
+    if (options.payer)
+        headers['x-payment-payer'] = options.payer;
+    // El sobre viaja tambien al cotizar: si esto ya es un ciclo, mejor que el
+    // otro extremo lo diga con un 508 antes de que nadie firme nada.
+    if (options.envelope)
+        Object.assign(headers, envelopeHeaders(options.envelope));
+    const res = await fetchLimited(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ prompt }),
+        timeoutMs: options.timeoutMs ?? 30_000,
+    });
+    if (res.status !== 402) {
+        throw new X402Error(res.status === 404
+            ? 'Ese agente no cobra por llamada (no tiene x402 activado).'
+            : `Esperaba un 402 con la cotización y respondió ${res.status}.`, res.status);
+    }
+    let quote;
+    try {
+        quote = JSON.parse(res.text);
+    }
+    catch {
+        throw new X402Error('La cotización no es JSON válido.');
+    }
+    const accept = quote.accepts?.find((a) => a.scheme === X402_SCHEME);
+    if (!accept) {
+        const vistos = quote.accepts?.map((a) => a.scheme).join(', ') || 'ninguno';
+        throw new X402Error(`Ese agente no acepta "${X402_SCHEME}". Esquemas que ofrece: ${vistos}.`);
+    }
+    return accept;
+}
+/**
+ * Paga una consulta a un endpoint x402 y devuelve la respuesta.
+ *
+ * Todas las comprobaciones van ANTES de firmar. Una firma de permit es una
+ * autorización para llevarse tu saldo: si se valida después, ya es tarde.
+ */
+export async function payAndAsk(wallet, account, endpoint, prompt, options) {
+    const url = await assertPublicUrl(endpoint, options);
+    const accept = options.quote ?? (await quoteAsk(endpoint, prompt, { payer: account.address, ...options }));
+    // ---- Lo que se comprueba antes de firmar --------------------------------
+    const amount = BigInt(accept.amount);
+    if (amount <= 0n)
+        throw new X402Error('La cotización pide un importe de cero o negativo.');
+    if (amount > options.maxSpend) {
+        throw new X402Error(`Pide ${amount} y tu tope es ${options.maxSpend}: no se firma.`);
+    }
+    if (accept.chainId !== options.chainId) {
+        throw new X402Error(`La cotización es de la cadena ${accept.chainId} y tú estás en la ${options.chainId}.`);
+    }
+    // Sin `strict: false` se rechazaria un `payTo` en minusculas, que es valido
+    // y es lo que devuelve cualquier servidor que no normalice a checksum.
+    if (!isAddress(accept.payTo, { strict: false })) {
+        throw new X402Error('El `payTo` de la cotización no es una dirección.');
+    }
+    if (options.expectedPayee && getAddress(accept.payTo) !== getAddress(options.expectedPayee)) {
+        // Sin esto, un endpoint secuestrado cobraría a nombre de otro: pagarías al
+        // atacante creyendo que pagas al agente que elegiste.
+        throw new X402Error(`La cotización cobra a ${accept.payTo} y esperabas a ${options.expectedPayee}: no se firma.`);
+    }
+    if (options.asset && getAddress(accept.asset) !== getAddress(options.asset)) {
+        throw new X402Error(`La cotización pide pagar en ${accept.asset} y esperabas ${options.asset}.`);
+    }
+    if (getAddress(accept.domain.verifyingContract) !== getAddress(accept.asset)) {
+        // El dominio EIP-712 tiene que ser el del propio token: si apunta a otro
+        // contrato, la firma valdría para algo distinto de lo que crees.
+        throw new X402Error('El dominio de firma no corresponde al token que se va a pagar.');
+    }
+    const ahora = Math.floor(Date.now() / 1000);
+    if (accept.deadline <= ahora + 30) {
+        throw new X402Error('La cotización caduca de inmediato: pide otra.');
+    }
+    if (accept.payerNonce === undefined) {
+        throw new X402Error('La cotización no trae el nonce del pagador. Vuelve a pedirla indicando `payer`, o léelo del token.');
+    }
+    // ---- Firma (sin gas, sin transacción) -----------------------------------
+    const signature = await wallet.signTypedData({
+        account,
+        domain: accept.domain,
+        types: PERMIT_TYPES,
+        primaryType: 'Permit',
+        message: {
+            owner: account.address,
+            spender: getAddress(accept.payTo),
+            value: amount,
+            nonce: BigInt(accept.payerNonce),
+            deadline: BigInt(accept.deadline),
+        },
+    });
+    const header = toBase64(JSON.stringify({
+        scheme: X402_SCHEME,
+        payer: account.address,
+        value: amount.toString(),
+        deadline: accept.deadline.toString(),
+        signature,
+    }));
+    // ---- Segunda llamada: se cobra y se responde en la misma ----------------
+    const res = await fetchLimited(url, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            'x-payment': header,
+            ...(options.envelope ? envelopeHeaders(options.envelope) : {}),
+        },
+        body: JSON.stringify({ prompt }),
+        timeoutMs: options.timeoutMs ?? (accept.maxTimeoutSeconds ?? 120) * 1000,
+    });
+    let body;
+    try {
+        body = JSON.parse(res.text);
+    }
+    catch {
+        throw new X402Error(`Respuesta ilegible del agente (HTTP ${res.status}).`, res.status);
+    }
+    if (res.status !== 200) {
+        // El 502 con `paymentTx` es el caso feo y hay que distinguirlo: te han
+        // cobrado y no han respondido, así que el hash es tu prueba para reclamar.
+        if (body.paymentTx) {
+            throw new X402Error(`El agente cobró (tx ${body.paymentTx}) pero no entregó respuesta: ${body.error ?? 'sin detalle'}`, res.status);
+        }
+        if (res.status === 508) {
+            throw new X402Error(`El agente rechazó la llamada por ciclo: ya había atendido esta cadena. ${body.error ?? ''}`.trim(), 508);
+        }
+        throw new X402Error(body.error ?? `El agente respondió ${res.status}.`, res.status);
+    }
+    if (typeof body.answer !== 'string' || !body.answer) {
+        throw new X402Error('El agente respondió 200 pero sin `answer`.');
+    }
+    return {
+        answer: body.answer,
+        paid: amount,
+        payee: getAddress(accept.payTo),
+        txHash: body.payment?.txHash,
+        endpoint: url.toString(),
+    };
+}
+/** base64 sin depender de Buffer, para que valga también en el navegador. */
+function toBase64(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = '';
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return typeof btoa === 'function'
+        ? btoa(binary)
+        : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            globalThis.Buffer.from(text, 'utf8').toString('base64');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx test/sdk.test.ts"
+    "test": "tsx test/envelope.test.ts && tsx test/sdk.test.ts && tsx test/x402.test.ts"
   }
 }