Metadata-Version: 2.4
Name: nyen-sdk
Version: 0.1.2
Summary: Official Python SDK for the NYEN /v1 public API — reads, satoshi-safe amounts, NTS token ops, SSE events, HMAC webhooks, and the non-custodial invoice/webhook payment flow.
Author: NYEN
License-Expression: MIT
Project-URL: Homepage, https://docs.nyen.cc/api
Project-URL: Documentation, https://docs.nyen.cc/api
Keywords: nyen,nts,blockchain,utxo,wallet,payments
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# nyen-sdk (Python)

> ⚠️ **TESTNET — data resets at mainnet launch.** The live `/v1` API currently
> serves an ephemeral test chain. Addresses, txids, and token ids you see now are
> **wiped when mainnet goes live** — don't hard-code them. Check `network` /
> `mainnet` on `/v1/chain` or `/v1/health` (reads `"testnet"` until launch).

Official Python SDK for the **NYEN `/v1` public API** — the same versioned edge
the TypeScript [`@nyen/sdk`](../nyen-sdk) wraps. Reads, satoshi-safe amounts, NTS
token ops, SSE events, HMAC webhooks, Login-with-NyenID, and a non-custodial
**invoice/webhook payment flow**. **Zero third-party dependencies** (pure
stdlib). Signing stays in the user's wallet — this SDK is keyless read + broadcast.

```bash
pip install nyen-sdk        # or: pip install -e Website/packages/nyen-sdk-py
```

## Read a balance (5 lines)

```python
from nyen_sdk import NyenClient

nyen = NyenClient("https://nyen.cc/v1", api_key="…")
info = nyen.address("N…")            # native NYEN + every NTS token, one call
print(info["native"]["balance"], [f'{t["balance"]} {t["name"]}' for t in info["tokens"]])
```

Amounts are **satoshi-exact** — never `float()` a balance:

```python
from nyen_sdk import to_sat, from_sat
to_sat("1.5")          # "150000000"
from_sat("150000000")  # "1.50000000"
nyen.balance("N…")     # int satoshis, exact
```

## Accept deposits with no node (merchant)

```python
from nyen_sdk import NyenClient, NyenPayments

pay = NyenPayments(NyenClient("https://nyen.cc/v1", api_key="…"))

# 1. create an invoice against YOUR OWN receive address + register a webhook
inv = pay.create_invoice(address="N…", amount="10",
                         callback_url="https://shop.example/nyen-hook")
print(pay.payment_uri(inv))          # nyen:N…?amount=10&req=inv_…  (QR / deep-link)

# 2. in your webhook endpoint (e.g. Flask):
res = pay.handle_webhook(request.headers, request.get_data(as_text=True))
if res.outcome == "paid":
    fulfill_order(res.invoice.metadata)      # HMAC verified, amount checked
```

`handle_webhook` verifies the Stripe-style HMAC (`x-nyen-signature`), matches the
confirmed deposit to the open invoice by address, checks the amount, and settles
it — you never run a node or poll the chain.

## Live-watch (no webhook endpoint)

```python
for evt in nyen.subscribe(channels=["address:N…"]):
    if evt["type"] == "address":
        print("deposit", evt["data"]["value"], evt["data"]["txid"])
        break
```

## Verify a webhook signature yourself

```python
ok = NyenClient.verify_webhook_signature(secret, ts, raw_body, sig_header)
```

## Surface

`NyenClient`: `health status chain block tx address balance address_utxos
address_history tokens token holders token_history identity fee_mint fee_estimate
decode_tx build_tx broadcast rpc verify_message subscribe events_stats
create_webhook list_webhooks get_webhook delete_webhook verify_webhook_signature`.

`NyenPayments`: `create_invoice payment_uri handle_webhook cancel_invoice
expire_stale sign_request verify_request` + `parse_payment_uri`.

Errors raise a typed `NyenError` with a **stable** `.code` (`"tx-rejected"`,
`"forbidden"`, …), `.rpc_code`, `.reason`, `.hint`, `.retryable` — mirroring the
`/v1` structured-error contract. See the [error index](https://docs.nyen.cc/api/errors).

MIT.
