Metadata-Version: 2.5
Name: limitguard
Version: 0.1.3
Summary: Official Python SDK for the LimitGuard Trust Intelligence API
Project-URL: Homepage, https://limitguard.ai
Project-URL: Documentation, https://docs.limitguard.ai
Project-URL: Issues, https://github.com/jwconsultancyteam/limitguard-mcp/issues
Author: LimitGuard
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,aml,compliance,kyb,limitguard,mcp,pep,risk,sanctions,trust,usdc,x402
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: respx; extra == 'dev'
Provides-Extra: evm
Requires-Dist: eth-account>=0.13; extra == 'evm'
Provides-Extra: solana
Requires-Dist: solana>=0.34; extra == 'solana'
Requires-Dist: solders>=0.21; extra == 'solana'
Description-Content-Type: text/markdown

# limitguard

Official Python SDK for the [LimitGuard](https://limitguard.ai) Trust Intelligence API: entity verification and risk scoring for EU businesses, paid per call in USDC over x402 or debited from an API key's prepaid balance.

## Install

```bash
pip install limitguard
```

With wallet support, for agents that pay per call:

```bash
pip install 'limitguard[solana]'   # Solana USDC
pip install 'limitguard[evm]'      # Base USDC
```

Python 3.10 or newer.

## Quickstart

```python
import asyncio
from limitguard import LimitGuardClient


async def main():
    async with LimitGuardClient(api_key="lg_live_...") as client:
        result = await client.check_entity("Acme BV", country="NL")
        print(result.trust_score, result.trust_level, result.recommendation)


asyncio.run(main())
```

`check_entity` returns a `TrustResponse` (`trust_score` 0-100, `trust_level`, `cluster`, `recommendation`, `confidence`, `top_factors`). `risk_score` is the cheaper two-source variant and returns a `RiskResponse`.

## Paying for calls

Two ways to satisfy the API's per-call price, and the client accepts either or both:

| You pass | What happens |
|---|---|
| `api_key=` on a **paid** tier (`indie` and up) | Each call is debited from the key's prepaid balance at list price. No per-call payment by the client. When the balance is short the API answers `402 insufficient_balance`: the client raises `PaymentRequiredError` unless a `wallet=` is set, in which case it pays that call by x402. |
| `wallet=` | The client pays each call in USDC over x402 automatically when the API answers 402, echoes the `X-Payment-Challenge` the 402 carried on the paid retry (the proof is only redeemable together with it), and signs that challenge with the paying wallet. |
| both | Calls are paid by the wallet and attributed to the key. |

A `free`-tier key identifies you and tracks usage; it holds no balance and does not pay for calls. On its own it will raise `PaymentRequiredError` on any paid endpoint. Add a wallet, or top up the key (`POST /v1/keys/upgrade/{tier}` or `POST /v1/keys/topup/{usd}` via x402).

Wallet example (Solana, needs the `[solana]` extra and a wallet holding USDC — no SOL: LimitGuard's fee payer co-signs the transaction and covers the network fee. Pass `broadcast=True` to `SolanaWallet` to pay it yourself instead, which requires SOL):

```python
from solders.keypair import Keypair
from limitguard import LimitGuardClient
from limitguard.x402 import SolanaWallet

wallet = SolanaWallet(keypair=Keypair.from_base58_string(private_key))
async with LimitGuardClient(wallet=wallet) as client:
    result = await client.check_entity("Acme BV", country="NL")
```

`SolanaWallet` pays in Solana USDC and `EvmWallet` in Base USDC; both take the key of the wallet the money leaves.

When the API quotes a settled-transfer price, the client also signs a short challenge message with the same wallet that sent the USDC and puts it in `X-Payment-Challenge-Signature`. The message is the protocol tag, the resource path, the chain id, your transaction hash or signature, and the challenge id — five lines, exactly as documented on the [x402 protocol page](https://docs.limitguard.ai/x402-protocol). It exists because a transaction hash is public the moment it lands: without the signature, anyone who saw it could redeem your payment. Your private key never leaves the wallet object, and a wallet that cannot sign still pays — the field is optional server-side today and will become required, so signing now means nothing breaks later.

A complete agent is in `examples/agent_with_wallet.py`, included in the source distribution (`pip download --no-binary :all: limitguard`).

## Errors

All exceptions subclass `LimitGuardError`: `AuthenticationError`, `PaymentRequiredError`, `RateLimitError`, `ValidationError`, `ServerError`. The client retries 429 and 5xx responses with backoff before raising.

## Links

- Documentation: https://docs.limitguard.ai
- Quickstart and a free sandbox key (mock data, no wallet): https://api.limitguard.ai/v1/quickstart
- x402 protocol: https://docs.limitguard.ai/x402-protocol
- Issues and support: https://github.com/jwconsultancyteam/limitguard-mcp/issues

## Version

```python
import limitguard
print(limitguard.__version__)
```

Releases are tagged `sdk-v<version>` and published to PyPI from that tag.
