Skip to main content
Todos los casos de uso
Cobro de API por usoSaaS

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.

AntesUn precio fijo por llamada, inflado para el peor caso
DespuésEl tope en el 402, el resto devuelto
402 → refund
el tope no usado vuelve on-chain
Pruébalo en el Sandbox
base × max
Tope en el 402
Precio base por el multiplicador máximo: lo máximo que paga quien llama
X-Pages
Tu API informa
El multiplicador viene de un header de la respuesta que eliges, limitado entre mínimo y máximo
USDC
Devolución on-chain
La diferencia vuelve desde la billetera del vendedor; los restos por debajo del costo de gas se condonan
off · on
Por despliegue
El cobro medido está apagado hasta que el operador lo habilita
Ejemplo ilustrativo · datos de demostración

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.

Llamada medida · ejemplo
call_8f21 · /extract
Devuelto · ejemplo
Tope en el 402US$ 0.80 · USDC
InformadoX-Pages: 17
RealUS$ 0.34
DevueltoUS$ 0.46 · on-chain
receipt-call8f21.json
✓ medido · devuelto · ejemplocall_8f21
El problema

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

Cómo lo hace el agente

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.

01
Crear
POST /v1/paywalls

Un paywall medido

02
402
Gate

El tope anunciado

03
Llamada
Tu API

Tu API informa el multiplicador

04
Medir
Gate

Real = base × multiplicador

05
Devolver
Billetera del vendedor

Tope menos real, on-chain

Arquitectura

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.

En código

El código, y lo que supone.

metered-api-access.ts
// 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.

Herramientas destacadas
POST /v1/paywalls

Crea el paywall; pricing_model metered recibe metered_config y un payTo aprovisionado.

Ver la referencia de meta-tools

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.

Acceso a API medido — CodeSpar | CodeSpar