Skip to main content
Todos os casos de uso
Cobrança de API por usoSaaS

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.

AntesUm preço fixo por chamada, inflado para o pior caso
DepoisO teto no 402, o resto devolvido
402 → refund
o teto não usado volta on-chain
Teste no Sandbox
base × max
Teto no 402
Preço base vezes o multiplicador máximo: o máximo que quem chama paga
X-Pages
A sua API informa
O multiplicador vem de um header da resposta que você escolhe, limitado entre mínimo e máximo
USDC
Devolução on-chain
A diferença volta da carteira do vendedor; resíduos abaixo do custo de gás são dispensados
off · on
Por implantação
A cobrança medida fica desligada até o operador ligá-la
Exemplo ilustrativo · dados de demonstração

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.

Chamada medida · exemplo
call_8f21 · /extract
Devolvido · exemplo
Teto no 402US$ 0.80 · USDC
InformadoX-Pages: 17
RealUS$ 0.34
DevolvidoUS$ 0.46 · on-chain
receipt-call8f21.json
✓ medido · devolvido · exemplocall_8f21
A dor

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

Como o agente faz isso

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.

01
Criar
POST /v1/paywalls

Um paywall medido

02
402
Gate

O teto anunciado

03
Chamada
Sua API

A sua API informa o multiplicador

04
Medir
Gate

Real = base × multiplicador

05
Devolver
Carteira do vendedor

Teto menos real, on-chain

Arquitetura

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.

Em código

O código, e o que ele pressupõe.

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);

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.

Ferramentas em destaque
POST /v1/paywalls

Cria o paywall; pricing_model metered recebe metered_config e um payTo provisionado.

Ver a referência das meta-tools

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.

Acesso a API medido — CodeSpar | CodeSpar