Cobre o teto. Devolva o que a chamada não usou.
A Extracta, neste exemplo, vende extração de documentos como API, e um recibo de uma página custa menos para processar do que um contrato de quarenta. Com um paywall medido no Gate, o 402 anuncia um teto: um preço base vezes um multiplicador máximo. Quem chama paga o teto; depois da chamada, o multiplicador que a Extracta informa num header da resposta define o preço real, limitado entre o mínimo e o máximo, e a diferença é devolvida on-chain a partir da carteira da Extracta. A cobrança medida fica desligada numa implantação até o operador ligá-la.
Uma extração, cobrada pelas páginas.
Um exemplo com dados de demonstração: um contrato por um paywall medido com base de US$ 0,02 por página e máximo de 40. O 402 pede o teto, US$ 0,80; a API informa 17 páginas, então o real é US$ 0,34 e US$ 0,46 volta on-chain.
- Quem chama paga o teto que o 402 anuncia
- A sua API informa o multiplicador num header da resposta
- A diferença é devolvida on-chain a partir da carteira do vendedor
Extrair os itens deste contrato de fornecedor.
O endpoint de extração pede no máximo US$ 0,80 no 402: pagando o teto; o real vem das páginas que ele informar.
A conversa é a parte fácil.
APIs cobradas por uso chutam. Um preço fixo por chamada cobra demais nos trabalhos fáceis ou perde dinheiro nos difíceis, e ninguém descobre qual até a fatura sair.
Cobrar preço fixo por chamada, inflado para o pior caso
O 402 anuncia um teto; o real segue o que a chamada usou
Correr atrás da diferença nos trabalhos difíceis
O multiplicador que a sua API informa precifica a chamada, até o teto
Deixar quem chama pagar a mais nos trabalhos fáceis
A diferença entre teto e real é devolvida on-chain
Devolver à mão e discutir
A devolução é enviada uma vez por liquidação e confirmada on-chain
Um paywall medido, do lado do vendedor.
O vendedor cria um paywall com pricing_model metered: um preço base, um multiplicador mínimo e máximo, e o header da resposta que traz o multiplicador. O 402 anuncia o teto, a base vezes o máximo. Depois da chamada, o gateway lê o header, limita o valor, cobra o real e devolve o resto on-chain a partir da carteira provisionada do vendedor. Uma implantação responde metered_not_enabled até o operador ligar a cobrança medida.
Um paywall medido
O teto anunciado
A sua API informa o multiplicador
Real = base × multiplicador
Teto menos real, on-chain
O paywall medido guarda um preço base em unidades atômicas de USDC, um multiplicador mínimo e máximo e o header da resposta a ler. O 402 anuncia base × máximo; quem chama paga. Depois da chamada ao upstream, o gateway lê o header (um valor ausente ou inválido conta como o mínimo), o limita, e a devolução de teto menos real é reservada uma vez por liquidação antes de sair da carteira provisionada do vendedor, e depois confirmada contra a chain. Criar ou liquidar um paywall medido é recusado até o operador ligar a cobrança medida.
O código, e o que ele pressupõe.
// 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);
Exemplo com o SDK publicado (@codespar/sdk 0.16.11). Os pré-requisitos estão nos comentários. Compilar não prova a integração: rode primeiro em modo de teste.
POST /v1/paywallsCria o paywall; pricing_model metered recebe metered_config e um payTo provisionado.
Comece com uma chave de teste.
Chaves de teste são gratuitas. Abra o sandbox, conecte os provedores que o seu projeto usa e veja quais ferramentas ele pode chamar antes de construir.