# 9. Integration Method Frame (Current Stack)

Baltex Protocol keeps partner integrations stable. The protocol expands the underlying route graph; the external methods and schemas remain consistent.

***

### 9.1 Authentication

Partner endpoints require an API key supplied via the `x-api-key` header.

***

### 9.2 Cross-Chain API (Summary)

<table><thead><tr><th width="75">Method</th><th width="334">Path</th><th>Purpose</th><th>Notes</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/v1/cross-chain/available-currencies</code></td><td>Discover supported currencies/networks.</td><td>Includes address regex, explorers, confirmations, fixed-rate support.</td></tr><tr><td><code>GET</code></td><td><code>/v1/cross-chain/rate</code></td><td>Quote a standard or fixed-rate exchange.</td><td><code>flow=standard|fixed-rate</code>; amount optional.</td></tr><tr><td><code>GET</code></td><td><code>/v1/cross-chain/rate/private</code></td><td>Quote a private exchange.</td><td>Requires <code>privateType</code>.</td></tr><tr><td><code>POST</code></td><td><code>/v1/cross-chain/exchange</code></td><td>Create standard exchange.</td><td><code>flow</code> required; <code>rateId</code> required for fixed-rate (valid 1 minute).</td></tr><tr><td><code>POST</code></td><td><code>/v1/cross-chain/exchange/private</code></td><td>Create private exchange.</td><td><code>privateType</code>: <code>privatePlus</code> (XMR only) or <code>efficient</code> (fast/cheap relay).</td></tr><tr><td><code>GET</code></td><td><code>/v1/cross-chain/exchange/status</code></td><td>Get exchange status by id.</td><td>Wrapper for standard/private status.</td></tr><tr><td><code>GET</code></td><td><code>/v1/cross-chain/exchange/list</code></td><td>List exchanges (last 24h) with filters.</td><td>Filter by status, networks, exchangeType.</td></tr></tbody></table>

## 9.3 DeFi API (Summary)

Currently documented DeFi networks: `eth`, `sol`, `sui`, `sei`, `arbitrum`, `base`, `bsc`, `cchain`, `celo`, `linea`, `matic`, `op`, `sonic`, `uni`.

***

<table><thead><tr><th width="82">Method</th><th>Path</th><th>Purpose</th><th>Notes</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/v1/defi/currency/info</code></td><td>Resolve token metadata by network + address.</td><td>Returns token info if exists.</td></tr><tr><td><code>GET</code></td><td><code>/v1/defi/available-currencies</code></td><td>List tokens for a network.</td><td>Supports page/limit pagination; network required.</td></tr><tr><td><code>GET</code></td><td><code>/v1/defi/quote</code></td><td>Quote an on-chain swap route.</td><td>Requires <code>network</code>, <code>fromTokenAddress</code>, <code>toTokenAddress</code>, <code>amount</code>, <code>slippage</code>, <code>referrerFee</code>.</td></tr><tr><td><code>POST</code></td><td><code>/v1/defi/transaction/swap</code></td><td>Build a transaction hash to sign.</td><td>Returns tx hash from provided data.</td></tr><tr><td><code>POST</code></td><td><code>/v1/defi/send/approve</code></td><td>Broadcast approval tx (if needed).</td><td>Partner provides signed tx payload.</td></tr><tr><td><code>POST</code></td><td><code>/v1/defi/send/swap</code></td><td>Broadcast swap tx.</td><td>Partner provides signed tx payload.</td></tr><tr><td><code>GET</code></td><td><code>/v1/defi/exchange/list</code></td><td>List DEX exchanges (last 24h) with filters.</td><td>Filter by <code>status</code>, <code>fromToken</code>, <code>toToken</code>, <code>network</code>.</td></tr></tbody></table>

## 9.4 End-to-End Sequence (Concept)

Across flows, the partner frame remains: `quote` → `create` → `user deposit/sign` → `status until terminal`.

***

### Sequence Diagram

```mermaid
sequenceDiagram
    participant P as Partner/UI
    participant A as Baltex API
    participant R as Router
    participant E as Executor
    participant V as Venues

    P->>A: GET /rate or /defi/quote
    A->>R: compute best route
    R-->>A: quote response
    A-->>P: quote response

    P->>A: POST /exchange or /defi/transaction/swap
    A->>E: create swap/exchange + lock plan
    E->>V: execute legs
    V-->>E: fills/txs

    P->>A: GET /exchange/status or /defi/exchange/list
    A-->>P: status until terminal
```

> **Figure 7.** Unified partner interaction sequence (Cross-Chain + DeFi).

***

### Interaction Steps

| # | Actor                   | Call                                            | Description                                            |
| - | ----------------------- | ----------------------------------------------- | ------------------------------------------------------ |
| 1 | Partner/UI → Baltex API | `GET /rate` or `/defi/quote`                    | Request a quote for the desired swap.                  |
| 2 | Baltex API → Router     | —                                               | Internally computes the best route.                    |
| 3 | Baltex API → Partner/UI | quote response                                  | Returns quote with rate, fees, and TTL.                |
| 4 | Partner/UI → Baltex API | `POST /exchange` or `/defi/transaction/swap`    | Creates the exchange and locks the plan.               |
| 5 | Baltex API → Executor   | create swap + lock plan                         | Hands off to the executor for leg dispatch.            |
| 6 | Executor → Venues       | execute legs                                    | Dispatches fills and transactions to liquidity venues. |
| 7 | Partner/UI → Baltex API | `GET /exchange/status` or `/defi/exchange/list` | Polls status until a terminal state is reached.        |

***

### Notes

* The partner frame is **identical for Cross-Chain and DeFi** flows — only the endpoint paths differ.
* The **Router** is internal to Baltex API; partners never call it directly.
* Step 7 (status polling) should continue until a terminal state (`finished`, `failed`, or `refunded`) is returned.