Cobra el tope. Devuelve lo que la llamada no usó.
Extracta, en este ejemplo, vende extracción de documentos como API, y un recibo de una página cuesta menos de procesar que un contrato de cuarenta. Con un paywall medido en Gate, el 402 anuncia un tope: un precio base por un multiplicador máximo. Quien llama paga el tope; después de la llamada, el multiplicador que Extracta informa en un header de la respuesta fija el precio real, limitado entre el mínimo y el máximo, y la diferencia se devuelve on-chain desde la billetera de Extracta. El cobro medido está apagado en un despliegue hasta que el operador lo habilita.
Una extracción, cobrada por sus páginas.
Un ejemplo con datos de demostración: un contrato por un paywall medido con base de US$ 0,02 por página y máximo de 40. El 402 pide el tope, US$ 0,80; la API informa 17 páginas, así que el real es US$ 0,34 y US$ 0,46 vuelve on-chain.
- Quien llama paga el tope que anuncia el 402
- Tu API informa el multiplicador en un header de la respuesta
- La diferencia se devuelve on-chain desde la billetera del vendedor
Extraer las partidas de este contrato de proveedor.
El endpoint de extracción pide como máximo US$ 0,80 en su 402: pagando el tope; el real sale de las páginas que informe.
La conversación es la parte fácil.
Las APIs cobradas por uso adivinan. Un precio fijo por llamada cobra de más en los trabajos fáciles o pierde en los difíciles, y nadie sabe cuál hasta que sale la factura.
Cobrar un precio fijo por llamada, inflado para el peor caso
El 402 anuncia un tope; el real sigue lo que usó la llamada
Perseguir la diferencia en los trabajos difíciles
El multiplicador que informa tu API pone precio a la llamada, hasta el tope
Dejar que quien llama pague de más en los trabajos fáciles
La diferencia entre tope y real se devuelve on-chain
Devolver a mano y discutirlo
La devolución se envía una vez por liquidación y se confirma on-chain
Un paywall medido, del lado del vendedor.
El vendedor crea un paywall con pricing_model metered: un precio base, un multiplicador mínimo y máximo, y el header de la respuesta que trae el multiplicador. El 402 anuncia el tope, la base por el máximo. Después de la llamada, el gateway lee el header, lo limita, cobra el real y devuelve el resto on-chain desde la billetera aprovisionada del vendedor. Un despliegue responde metered_not_enabled hasta que el operador habilita el cobro medido.
Un paywall medido
El tope anunciado
Tu API informa el multiplicador
Real = base × multiplicador
Tope menos real, on-chain
El paywall medido guarda un precio base en unidades atómicas de USDC, un multiplicador mínimo y máximo y el header de la respuesta a leer. El 402 anuncia base × máximo; quien llama lo paga. Después de la llamada al upstream, el gateway lee el header (un valor ausente o inválido cuenta como el mínimo), lo limita, y la devolución de tope menos real se reserva una vez por liquidación antes de salir de la billetera aprovisionada del vendedor, y luego se confirma contra la chain. Crear o liquidar un paywall medido se rechaza hasta que el operador habilita el cobro medido.
El código, y lo que supone.
// Prerequisites: CODESPAR_API_KEY with the admin role, a deployment where the // operator enabled metered pricing (otherwise the API answers // metered_not_enabled), and a consumer whose provisioned wallet receives the // payments and sends the refunds. import { CodeSpar } from "@codespar/sdk"; const cs = new CodeSpar(); // the seller's paywall: US$ 0.02 per page, up to 40 pages; the 402 asks for the // ceiling (US$ 0.80) and the X-Pages header of the response sets the actual const res = await cs.api.response("post", "/v1/paywalls", { body: { slug: "extract", name: "Document extraction", upstream_url: "https://api.extracta.example/extract", price: "0.02", pricing_model: "metered", metered_config: { basis: "units", base_atomic: "20000", min_mult: 1, max_mult: 40, units_header: "X-Pages" }, payto: { kind: "provisioned" }, consumer_id: "user_0000", }, }); console.log(res.status, res.ok ? res.data : null);
Ejemplo con el SDK publicado (@codespar/sdk 0.16.11). Los requisitos están en los comentarios. Compilar no prueba la integración: ejecútalo primero en modo de prueba.
POST /v1/paywallsCrea el paywall; pricing_model metered recibe metered_config y un payTo aprovisionado.
Empieza con una clave de prueba.
Las claves de prueba son gratuitas. Abre el sandbox, conecta los proveedores que usa tu proyecto y mira qué herramientas puede llamar antes de construir.