# BitMomo Rust SDK
Accept crypto payments in your Rust application and verify BitMomo webhooks.
Async client on `reqwest` (rustls by default), exact decimal money, and a
webhook verifier you can use without the HTTP client.
> **Test money only.** BitMomo currently runs on test networks. Live API keys
> are disabled, so nothing you do with this SDK moves real money.
Guides and the API reference: https://docs.bitmomo.app
## Install
```bash
cargo add bitmomo
```
Rust 1.88 or newer. Use it from any Tokio runtime.
## Create a payment
```rust
use bitmomo::{Client, CreatePaymentParams, Decimal};
let client = Client::new(std::env::var("BITMOMO_API_KEY")?, "https://api.dev.bitmomo.app")?;
let params = CreatePaymentParams::new(Decimal::new("150.00")?, "USDT_TRC20")
.order_id("order-1001")
.idempotency_key("order-1001"); // reuse the same key if you retry
let payment = client.create_payment(¶ms).await?;
println!("{} {} {}", payment.deposit_address, payment.crypto_amount, payment.qr_code_data);
```
Show the customer `qr_code_data` (or `deposit_address` and `crypto_amount`).
Then wait for the webhook, or poll with `get_payment_status` and `get_payment`.
## Verify webhooks
Verify the **raw** request body. Keep both secrets during the 24 hours after
you rotate.
```rust
use bitmomo::webhooks::{verify_event, DeliveryDedupeCache, VerifyOptions, WebhookSecret};
let opts = VerifyOptions::new(vec![WebhookSecret::new(1, secret)])
.timestamp(headers.get("X-Webhook-Timestamp"))
.key_version(headers.get("X-Webhook-Key-Version"));
match verify_event(&body, signature, &opts) {
Ok(envelope) if dedupe.seen(&envelope.delivery_id) => { /* already handled: 200 */ }
Ok(envelope) => { /* handle the event, then 200 */ }
Err(reason) => { /* 400; reason says why, e.g. "stale-timestamp" */ }
}
```
Only need webhooks? Turn off the HTTP client:
```toml
bitmomo = { version = "0.1", default-features = false }
```
Deliveries arrive at least once. Store processed delivery IDs durably if a
duplicate would cause a second effect.
## Everything the client can do
| `create_payment` | `POST /api/v1/gateway/payments` |
| `get_payment` | `GET /api/v1/gateway/payments/{id}` |
| `get_payment_status` | `GET /api/v1/payments/{id}/status` |
| `list_payments` | `GET /api/v1/gateway/payments` |
| `request_payout` | `POST /api/v1/gateway/payouts` |
| `get_rates` | `GET /api/v1/rates` |
| `get_balances` | `GET /api/v1/gateway/balances` |
| `get_webhook_config` | `GET /api/v1/gateway/webhooks/config` |
| `update_webhook_config` | `PUT /api/v1/gateway/webhooks/config` |
| `rotate_webhook_secret` | `POST /api/v1/gateway/webhooks/config/rotate` |
| `delete_webhook_config` | `DELETE /api/v1/gateway/webhooks/config` |
| `create_payment_link` | `POST /api/v1/gateway/payment-links` |
| `list_payment_links` | `GET /api/v1/gateway/payment-links` |
| `get_payment_link` | `GET /api/v1/gateway/payment-links/{id}` |
Each API key carries scopes. A key without the right scope gets an error with
status 403.
## Errors and retries
Every failure is a `bitmomo::Error` with `status`, `code`, `message`,
`request_id` and `retriable`. `status` is 0 when no response arrived
(`NETWORK_ERROR`, with the cause in `source()`) or the response broke the
contract (`SCHEMA_ERROR`).
- Reads retry automatically on 429 and 5xx, twice by default
(`Client::builder(..).max_retries(n)`), honouring `Retry-After` up to 60
seconds.
- Writes are never retried for you. Retry with the same idempotency key;
`request_payout` refuses to send without one.
- Redirects are refused, so your API key is never sent to another host.
- The base URL must be an HTTPS origin (plain HTTP only for localhost).
## Money
Money is `bitmomo::Decimal`, an exact decimal string such as `"150.00"`. It
never passes through `f64`. Convert it with your decimal crate, for example
`rust_decimal::Decimal::from_str(d.as_str())`. The `f64` fields on `Balances`
are for display only; use the `*_exact` fields for arithmetic.
## License
MIT