Saltar para o conteúdo principal
O SDK Python é adequado para serviços de backend, tarefas de dados, Agents automatizados e scripts de processamento em lote. acedatacloud é responsável pelas chamadas de API, e acedatacloud-x402 é responsável por assinar o cabeçalho de requisição PAYMENT-SIGNATURE. Código-fonte e endereços dos pacotes:

Instalar dependências

Se for usar upto, também será necessário chamar uma vez a CLI de aprovação Permit2, e essa CLI depende de web3:
Saída da verificação de instalação e importação em um Python venv limpo:
Explicação dos resultados:
  • Tanto acedatacloud quanto acedatacloud-x402 podem ser instalados e importados a partir do PyPI.
  • pip install 'acedatacloud-x402[cli]' inclui a CLI approve-permit2, usada para a autorização prévia de upto.

Exemplo Base

O exemplo abaixo não requer API Token. A chave privada da carteira é usada apenas para assinatura local e não será enviada ao Ace Data Cloud.
Atualmente, o SDK Python retorna um dict, portanto o exemplo usa res["choices"][0]["message"]["content"]. Não assuma diretamente que ele necessariamente possui o atributo .choices.

Exemplo Solana

Solana usa uma secret key codificada em base58:
O fluxo Solana construirá e enviará uma transação SPL USDC TransferChecked e, então, colocará a assinatura da transação no envelope PAYMENT-SIGNATURE. A nova tentativa paga do Solana já retornou HTTP 200 e ADC_SOLANA_E2E_OK na API de produção. A consulta RPC pública desta vez encontrou limitação de taxa, e não confirmou de forma estável a signature on-chain; quando for necessário reconciliar, use seu próprio RPC Solana para consultar essa transação.

Cliente Async

O mesmo payment handler pode ser usado com AsyncAceDataCloud:

Usar medição posterior com upto

O custo real de APIs como complementação de chat e chamadas de modelo pode só ser conhecido após o término da resposta. Nesse caso, a API pode retornar simultaneamente exact e upto. Se quiser priorizar upto:
Resultado da execução do programa upto na Base:
Confirmação on-chain:
Explicação dos resultados:
  • content ADC_BASE_UPTO_OK indica que a requisição realmente entrou na API do modelo.
  • settled value 3 atomic USDC indica que upto é liquidado de acordo com o uso real, em vez de descontar o limite máximo completo.
  • settlement tx pode ser aberto no BaseScan; ao reconciliar, salve o tx hash, payer, completion id e o resumo da requisição.
upto usa Permit2 para autorizar um limite máximo, e o valor real da liquidação não pode exceder esse limite. Antes do primeiro uso, é necessário fazer uma vez approve(Permit2, amount) para o USDC na cadeia de destino. Método CLI:
Método programático:
Esse helper é idempotente. Se a allowance já for suficiente, ele retornará {"skipped": true} e não enviará novamente uma transação on-chain.

Assinatura de baixo nível

Se não usar o SDK, você também pode chamar diretamente a função de assinatura de baixo nível:
As funções de baixo nível são adequadas para testes, camada de proxy, integração de gateway ou SDKs não oficiais. Para código de negócios comum, dê prioridade a create_x402_payment_handler.