Metadata-Version: 2.4
Name: grid402
Version: 2.2.0
Summary: SDK Python oficial do Grid402: Micropagamentos HTTP 402 na Base para Agentes Autonomos e IA
Author-email: Grid402 Team <contato@grid402.com.br>
License-Expression: MIT
Project-URL: Homepage, https://grid402.com.br
Project-URL: Documentation, https://grid402.com.br/docs
Project-URL: Repository, https://github.com/thiagobg90/Grid402
Project-URL: Issues, https://github.com/thiagobg90/Grid402/issues
Keywords: x402,http-402,micropayments,base,coinbase-agentkit,agentic-web,mcp,ai-agents
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Grid402 - SDK Python Oficial

Biblioteca Python oficial para consumo dos servicos do ecossistema **Grid402** e liquidacao autonoma de micropagamentos sob o protocolo HTTP 402 na rede Base.

Projetada especificamente para agentes autonomos de inteligencia artificial, frameworks como Coinbase AgentKit, LangChain, CrewAI e desenvolvedores que buscam APIs abertas sem contas, cadastros ou cartoes de credito.

---

## Recursos Principais

- **10 Ferramentas Integradas:** Indicadores macroeconomicos (Selic, CDI, IPCA), feriados nacionais e bancarios ANBIMA, CNPJ da Receita Federal, CEP postal e IBGE, cotacoes Forex e Cripto spot, resolucao DNS, auditoria TLS e SSL, analise ASN e BGP e status do ecossistema.
- **Zero Cadastro e Zero Friccao:** Sem necessidade de chaves de API estaticas ou contratos mensais.
- **Modo Sandbox Gratuito:** Teste e homologue localmente sem custos informando `sandbox=True`.
- **Integracao Nativa com IA:** Compativel com Coinbase Developer Platform (CDP) AgentKit, LangChain e CrewAI.
- **Validacao Estrita Pydantic:** Schemas tipados e compativeis com PEP 561 (`py.typed`).
- **Arquitetura Resiliente:** Construido com a biblioteca padrao do Python para maxima leveza e portabilidade.

---

## Instalacao

Instale o pacote diretamente do PyPI:

```bash
pip install grid402
```

---

## Inicio Rapido

### 1. Consultas em Modo Sandbox (Sem Custo)

Ideal para testes locais, ambientes de integracao continua e desenvolvimento:

```python
from grid402 import Grid402Client

# Inicializa o cliente apontando para o ambiente de testes gratuito
client = Grid402Client(sandbox=True)

# Consulta cadastral de Pessoa Juridica na Receita Federal
cnpj_data = client.get_cnpj("00.000.000/0001-91")
print("Razao Social:", cnpj_data.get("razao_social"))

# Resolucao de endereco postal e codigo IBGE
cep_data = client.get_cep("01310-100")
print("Logradouro:", cep_data.get("logradouro"), "-", cep_data.get("localidade"))

# Cotacoes fiduciarias oficiais
forex_data = client.get_forex()
print("USD para BRL:", forex_data.get("USD", {}).get("bid"))
```

---

### 2. Tratamento Estruturado de HTTP 402

Quando chamado sem comprovante de pagamento, o Grid402 retorna uma resposta estruturada contendo o desafio com pre-visualizacao parcial dos dados (teaser data):

```python
from grid402 import Grid402Client, Grid402PaymentRequiredError

# Cliente com raise_for_payment ativado
client = Grid402Client(raise_for_payment=True)

try:
    dados = client.get_cnpj("00000000000191")
except Grid402PaymentRequiredError as erro:
    print("Desafio recebido:")
    print("Valor exigido:", erro.price_usdc, erro.token)
    print("Carteira recebedora:", erro.recipient)
    print("Rede:", erro.network)
    print("Dados parciais (amostra gratuita):", erro.preview_data)
```

---

### 3. Utilizacao com Coinbase AgentKit e Auto-Liquidacao

Agentes autonomos equipados com carteiras CDP na rede Base podem liquidar chamadas M2M (Machine-to-Machine) de forma transparente:

```python
from grid402 import Grid402ActionProvider

# Provedor compativel com Coinbase AgentKit
provider = Grid402ActionProvider()

# Ao fornecer a instancia de carteira CDP do agente (wallet_provider),
# o provedor detecta o 402, transfere o USDC e repassa os dados completos
resultado = provider.query_cnpj("00000000000191", wallet_provider=meu_wallet_provider)
print("Dados completos:", resultado)
print("Comprovante on-chain:", resultado.get("_x402_settlement"))
```

---

### 4. Schemas Tipados Pydantic

Para fluxos de trabalho tipados e validacao antecipada:

```python
from grid402 import CnpjInput, CepInput, DnsInput, SslInput, AsnInput, IndicatorsInput, HolidaysInput

# Validacao de entrada antes do envio
payload_cnpj = CnpjInput(cnpj="00.000.000/0001-91")
payload_cep = CepInput(code="01310100")
payload_dns = DnsInput(domain="base.org")
payload_holidays = HolidaysInput(year=2026)
```

---

## Catalogo de Ferramentas

| Metodo | Descricao | Preco Base (USDC) |
|---|---|---|
| `get_summary()` | Resumo operacional consolidado de saude | Gratuito |
| `get_forex()` | Cotacoes cambiais oficiais de USD, EUR e GBP para BRL | 0.0005 |
| `get_crypto(symbol)` | Precos spot de BTC, ETH, SOL e USDC | 0.0005 |
| `get_dns(domain)` | Resolucao DNS com registros A, AAAA, MX, TXT, NS e CNAME | 0.0005 |
| `get_ssl(host)` | Inspecao e auditoria de certificado TLS e SSL na porta 443 | 0.0005 |
| `get_asn(ip)` | Inteligencia de roteamento BGP, bloco alocado e ASN | 0.0005 |
| `get_cep(code)` | Consulta de logradouro postal brasileiro e codigo IBGE | 0.0005 |
| `get_cnpj(cnpj)` | Dados cadastrais completos de PJ na Receita Federal | 0.0020 |
| `get_indicators()` | Indicadores macroeconomicos oficiais (Selic meta e diaria, CDI anual e IPCA) | 0.0005 |
| `get_holidays(year)` | Calendario oficial de feriados nacionais e bancarios ANBIMA | 0.0005 |

---

## Licenca

Distribuido sob os termos da licenca MIT. Consulte o arquivo `LICENSE` para detalhes.

