Metadata-Version: 2.4
Name: usdctofiat
Version: 0.1.0
Summary: USDCtoFiat Python client. cashout(mode=fast|best) on Base. Galleon Labs.
Author: Galleon Labs
License: MIT
Project-URL: Homepage, https://usdctofiat.xyz
Project-URL: Documentation, https://usdctofiat.xyz/developers
Project-URL: Repository, https://github.com/ADWilkinson/usdctofiat-python
Keywords: usdctofiat,usdc,offramp,base,galleon
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: eth-abi>=5
Requires-Dist: eth-utils>=5
Requires-Dist: pycryptodome>=3.20
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: respx>=0.22; extra == "dev"
Dynamic: license-file

# usdctofiat

USDCtoFiat by Galleon Labs. Python client for non-custodial USDC-to-fiat cash-out on Base.

Built on the public Peer/ZKP2P protocol. Not a Peer Cash product. Not Peerlytics.

https://usdctofiat.xyz · https://usdctofiat.xyz/developers

## Install

```bash
pip install usdctofiat
```

This repository is the source. A PyPI release is a separate publish step and is not part of this scaffold.

## Cash out

`mode` is required. Fast is 0% spread / 0 bps and earns `TOFIAT`. Best is Delegate at 10 bps.

The client never takes a wallet private key. Pass a signer callback that submits an unsigned tx, or call `prepare()` and sign in the host.

```python
from usdctofiat import cashout, create_offramp

def signer(tx):
    # Host signs and submits {to, data, value, chain_id}. Return the tx hash.
    return submit(tx)

order = cashout(
    mode="fast",
    signer=signer,
    amount="100",
    currency="EUR",
    platform="revolut",
    payee="alice",
)
print(order.deposit_id, order.tx_hash, order.mode)
```

Strings and numbers are human USDC amounts. An `int` is exact six-decimal base units.

## Prepare without a signer

```python
offramp = create_offramp()
prepared = offramp.prepare(
    mode="fast",
    amount="100",
    currency="EUR",
    platform="revolut",
    payee="alice",
)
for tx, step in zip(prepared.txs, prepared.steps):
    print(step, tx.to, tx.data[:10])
```

`create_offramp()` locks attribution to `peer-ref-TOFIAT` then `galleonlabs`. Inbound `referral_code` and `peer-ref-*` values are discarded. Extra analytics referrers may be appended after those two.

## What v1 does

- Fast prepare-path: public curator `POST /v2/makers/create` (no API key), then unsigned USDC `approve` + EscrowV2 `createDeposit` at the oracle floor (0 bps, no Delegate vault), with ERC-8021 on every tx.
- Best is the same deposit plus a Delegate `setRateManager` hook so the API exists. The hook is encoded after a `deposit_id` is known. No Relay. No attestation mint.
- `estimate`, `watch`, `withdraw` / `close`, and `deposits` talk to the public indexer.

There is no `POST /cashout`. Deposit creation is onchain.

## Base mainnet

| | |
| --- | --- |
| Chain | 8453 |
| USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| EscrowV2 | `0x777777779d229cdF3110e9de47943791c26300Ef` |

HTTP: `https://api.zkp2p.xyz` and `https://indexer.zkp2p.xyz/v1/graphql`.

## Agno toolkit draft

A local `UsdctoFiatTools` draft lives in [`examples/agno/`](examples/agno/).
It is a copy-ready scaffold for a future `agno-agi/agno` PR (`agno[usdctofiat]`).
It is not an installable Agno first-party tool. Do not open that host PR
while the external cap is full. Mode is required. No private-key constructor.

## Licence

MIT
