> For the complete documentation index, see [llms.txt](https://docs.baltex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.baltex.io/whitepaper/12.-data-model-reference.md).

# 12. Data Model (Reference)

The protocol can be modeled with a small set of persistent entities: Swap/Exchange, RoutePlan, Leg, and Asset metadata.

***

### Entity Diagram

```mermaid
erDiagram
    SwapExchange {
        string id
        string type "standard | private | defi"
        string status
        datetime created
        object request "from/to, networks, amount"
        object deposit_instructions
        string recipient
    }

    RoutePlan {
        string swap_id
        string snapshot_id
        array legs
        number score
        number ttl
    }

    Leg {
        string leg_id
        string swap_id
        string kind "DEX | CEX | provider | relay"
        string status
        object external_refs
        object amounts
        object timestamps
    }

    Asset {
        string ticker
        string address
        string network
        number decimals
        string regexAddress
        array explorers
    }

    SwapExchange ||--|| RoutePlan : "1:1"
    RoutePlan ||--|{ Leg : "1:N"
    SwapExchange ||--|{ Leg : "1:N"
    SwapExchange }|--|| Asset : "uses"
```

> **Figure 8.** Reference data model (Swap/Exchange ↔ RoutePlan ↔ Leg).

***

### Entities

#### SwapExchange

<table><thead><tr><th width="143">Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td><td>Unique exchange identifier.</td></tr><tr><td><code>type</code></td><td>enum</td><td><code>standard</code>, <code>private</code>, or <code>defi</code>.</td></tr><tr><td><code>status</code></td><td>enum</td><td>Current state in the exchange lifecycle.</td></tr><tr><td><code>created</code></td><td>datetime</td><td>Timestamp of exchange creation.</td></tr><tr><td><code>request</code></td><td>object</td><td>Swap intent: from/to assets, networks, amount.</td></tr><tr><td><code>deposit_instructions</code></td><td>object</td><td>Address and memo for the user's inbound deposit.</td></tr><tr><td><code>recipient</code></td><td>string</td><td>Destination address for the output asset.</td></tr></tbody></table>

#### RoutePlan

<table><thead><tr><th width="138">Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>swap_id</code></td><td>string</td><td>Reference to the parent SwapExchange.</td></tr><tr><td><code>snapshot_id</code></td><td>string</td><td>Graph snapshot used to compute this plan.</td></tr><tr><td><code>legs</code></td><td>array</td><td>Ordered list of leg references.</td></tr><tr><td><code>score</code></td><td>number</td><td>Composite score from the routing engine.</td></tr><tr><td><code>ttl</code></td><td>number</td><td>Expiry time; plan is stale after this.</td></tr></tbody></table>

#### Leg

| Field           | Type   | Description                                   |
| --------------- | ------ | --------------------------------------------- |
| `leg_id`        | string | Unique leg identifier.                        |
| `swap_id`       | string | Reference to the parent SwapExchange.         |
| `kind`          | enum   | `DEX`, `CEX`, `provider`, or `relay`.         |
| `status`        | enum   | Current execution state of this leg.          |
| `external_refs` | object | Tx hashes, order IDs, or provider references. |
| `amounts`       | object | Input/output amounts and fees for this leg.   |
| `timestamps`    | object | Created, updated, and confirmed timestamps.   |

#### Asset

| Field          | Type   | Description                                 |
| -------------- | ------ | ------------------------------------------- |
| `ticker`       | string | Asset symbol (e.g. `USDT`).                 |
| `address`      | string | Contract or native address on the network.  |
| `network`      | string | Network identifier (e.g. `eth`, `sol`).     |
| `decimals`     | number | Token decimal precision.                    |
| `regexAddress` | string | Validation pattern for recipient addresses. |
| `explorers`    | array  | Block explorer URLs for this network.       |

***

### Relationships

| Relationship             | Cardinality | Description                                                    |
| ------------------------ | ----------- | -------------------------------------------------------------- |
| SwapExchange → RoutePlan | 1:1         | Each exchange has exactly one locked route plan.               |
| RoutePlan → Leg          | 1:N         | A route plan is composed of one or more ordered legs.          |
| SwapExchange → Leg       | 1:N         | A swap directly references all its legs for status tracking.   |
| SwapExchange → Asset     | uses        | Exchange references Asset metadata for validation and display. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.baltex.io/whitepaper/12.-data-model-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.