canonical: https://jentic.com/apis/exchange.api.bity.com/bity

# Exchange Api Bity Bity Exchange API

Bity Exchange is a Swiss crypto-fiat exchange API for getting quotes, placing orders, and tracking the lifecycle of crypto-to-fiat and fiat-to-crypto trades. The spec covers currency lookups, single and multiple order estimates, order creation and cancellation, and bank-transfer QR-bill generation for Swiss settlement. Agents use it to obtain pricing, execute orders, and reconcile bank transfers in CHF, EUR, and supported crypto pairs.

## For AI agents

Get crypto-fiat exchange quotes, place orders, and track fills on Bity's Swiss crypto exchange.

## Scope

Does not handle wallet custody, derivatives, or non-Swiss-bank settlement - use for crypto-fiat order estimates, placement, and Swiss QR-bill generation only.

## Capabilities

- List supported currencies for crypto and fiat pairs
- Estimate a single order to retrieve the indicative rate before committing
- Estimate multiple orders in a batch for portfolio-style pricing
- Place an order to convert between crypto and fiat assets
- Retrieve the status and details of a specific order by uuid
- Cancel a placed order before it settles
- Generate a Swiss bank-transfer QR-bill for an order's fiat leg

## Use cases

### Crypto-to-fiat off-ramp

A treasury agent moves crypto into a Swiss bank account by placing a sell order on Bity. The agent estimates the order, creates it, and then monitors the order status until the fiat leg settles to the recipient bank account, all without manually using the Bity web app.

Example prompt: Estimate selling 0.5 BTC to CHF via `/orders/estimate`, create the order via POST /orders with the bank-account payout details, then poll `/orders/{order_uuid}` until status is 'executed'.

### Fiat-to-crypto on-ramp with QR-bill

A retail agent helps a Swiss customer buy crypto by placing a fiat-to-crypto order and returning the Swiss QR-bill. The customer scans the QR-bill in their banking app, the bank transfer arrives at Bity, and Bity executes the conversion to the customer's crypto wallet.

Example prompt: Create an order to buy 0.1 BTC with CHF on Bity, then call `/orders/{order_uuid}/bank_transfer_qr_bill` to retrieve the QR-bill payload for the customer.

### Multi-pair quote dashboard

A trading dashboard wants live quotes across several pairs at once. The integration agent calls `/orders/estimate/multiple` with a batch of pairs and amounts, then renders the indicative rates side by side for the user - much faster than calling the single-estimate endpoint per pair.

Example prompt: Call POST `/orders/estimate/multiple` with a batch of three pairs (BTC/CHF, ETH/CHF, BTC/EUR) and 1-unit input amounts, then return the rates as a table.

### AI agent crypto desk via Jentic

A treasury AI assistant integrated through Jentic accepts natural-language instructions like 'sell 0.2 BTC into CHF when the rate is above 60k' and converts them into Bity estimate plus order calls. Jentic isolates the OAuth tokens so the assistant never holds the raw client credentials.

Example prompt: Use Jentic to search for 'estimate a bity crypto order', load the operation, and return an estimate for selling 0.2 BTC into CHF.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/currencies` | List supported currencies |
| GET | `/currencies/{currency_code}` | Retrieve a single currency |
| POST | `/orders/estimate` | Estimate a single order |
| POST | `/orders/estimate/multiple` | Estimate multiple orders in a batch |
| POST | `/orders` | Create an order |
| GET | `/orders/{order_uuid}` | Retrieve a specific order |
| GET | `/orders/{order_uuid}/bank_transfer_qr_bill` | Generate a Swiss QR-bill for an order |
| POST | `/orders/{order_uuid}/cancel` | Cancel a placed order |

## Key resources

- **Currencies** — Supported crypto and fiat currency metadata
- **Orders** — Estimates, order creation, status, cancellation, and QR-bill generation

## Why Jentic

- **Setup:** Wiring the Bity Exchange API by hand means running its OAuth2 client-credentials flow, refreshing tokens, and tracking the currency, order-estimate, and QR-bill endpoints yourself. Through Jentic you install once, import Bity from the API Directory, store the OAuth client credentials once, and your agent calls it.
- **Permission scoping:** Bity puts the order id in the URL path (`/orders/{order_uuid}`), so a rule can pin your agent to one order for status reads and QR-bill retrieval. You choose the operations it may call, so order cancellation via `/orders/{order_uuid}/cancel` is not included unless you add it.
- **Credential handling:** Your Bity OAuth client credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'estimate a crypto order' or 'generate a Swiss QR bill', and Jentic returns the matching Bity operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Kraken** — Global crypto exchange with deep order books and broad pair coverage
- **Binance** — World's largest crypto exchange by volume with extensive pair coverage
- **Bitstamp** — European crypto exchange with EUR pairs and bank settlement
- **CoinMarketCap** — Provides market data and reference prices for sanity-checking exchange quotes

## FAQ

### What authentication does the Bity Exchange API use?

Bity uses OAuth 2.0 with three flows in the spec: bity_account_client_oauth, bity_account_oauth, and client_oauth. Through Jentic, OAuth tokens are stored encrypted in your Jentic One instance and exchanged for scoped credentials at call time, so the raw client secret never reaches the agent.

### Can I get a price estimate before placing an order on Bity?

Yes. POST `/orders/estimate` returns a quote for a single pair, and POST `/orders/estimate/multiple` returns quotes for a batch in one call. Use these before calling POST /orders to commit a trade.

### How do I generate a Swiss QR-bill for a Bity order?

Once an order is created, call GET `/orders/{order_uuid}/bank_transfer_qr_bill` to retrieve the QR-bill payload. The customer can then scan it in any Swiss banking app to send the fiat leg of the transfer.

### What are the rate limits for the Bity Exchange API?

The OpenAPI spec does not publish explicit rate limits. Bity enforces per-client throttling at the gateway, so agents should handle 429 responses with backoff and respect any Retry-After header returned.

### How do I place a crypto-fiat order through Jentic?

Run pip install jentic, search for 'place a bity exchange order', load the POST /orders operation, and execute it with the input and output currencies and amount. Jentic supplies the input schema so the agent can place the order without spec browsing.

### Can I cancel a Bity order after creating it?

Yes, while it is still cancellable. POST `/orders/{order_uuid}/cancel` cancels the order before the fiat leg settles. Once funds have moved, cancellation is no longer possible.

### Can I limit what my agent is allowed to do with the Bity Exchange API?

Yes. Because Jentic One is self-hosted, you set the rules that decide which Bity operations and credentials your agent may use. You pick the exact operations it can call, so order cancellation via POST `/orders/{order_uuid}/cancel` stays off unless you add it, and you can pin the agent to a single order by its path id (`/orders/{order_uuid}`) for status reads and QR-bill retrieval only. Your OAuth client credentials are injected at call time and never reach the agent's prompt or logs.