# Routes Engine

The Routes Engine is the programmable heart of Reveel PayID. It determines how incoming payments should be **processed, routed, and settled**, based on **user-defined rules**. This engine is what allows Reveel to go beyond simple address redirection and support intelligent, omnichain payment behavior.

***

### What is a Route?

A **route** is a logical set of conditions and outcomes configured by the user (or application) that defines:

* **What payment types are accepted** (by network, token, sender wallet)
* **Where those payments should end up** (target chain, token, wallet)
* **Whether a swap or bridge is needed** (optional, configurable)

Each user can define **multiple routes**, allowing fine-grained control over how different types of incoming payments are handled.

***

### Why It Matters

Without routing, a PayID would just be a static alias for a wallet. With the Routes Engine, Reveel unlocks:

* **Network abstraction**: sender doesn’t need to know recipient’s chain
* **Token normalization**: receive USDC even if sender sends USDT
* **Smart fallback logic**: default wallets for unknown senders or tokens
* **Enterprise-style flexibility**: tailor rules by partner, product, use case

It brings Web2-style conditional logic into the programmable payment space.

***

### Routing Rules: How They Work

Each route contains **match conditions** and **output instructions**.

#### Match Conditions (Inputs)

These define **when** a route should activate:

* `incomingToken`: Which tokens should trigger this route
* `incomingNetwork`: Which chains the payment may come from
* `incomingWallets`: (Optional) Which sender wallets this route applies to

#### Output Instructions

These define **what to do** with the matched funds:

* `swapToken`: Which token the user prefers to receive (optional)
* `swapNetwork`: Which chain to settle the funds on (optional)
* `outgoingWallet`: Final destination wallet

***

### Deterministic vs. Flexible Logic

Reveel allows routes to be either:

* **Strictly deterministic**: routes trigger only when all match conditions are met
* **Fallback-friendly**: if no exact match, default route can apply

This makes the system powerful enough for:

* Basic personal use (receive USDC on Base always)
* Complex app flows (route payments from `App A` to Chain A, `App B` to Chain B)

***

### Multi-Route Architecture

Users can have **multiple active routes**, and the engine evaluates them in order of **specificity and priority**. This allows:

* **Granular override**: route payments from a specific sender differently
* **General rules**: apply a catch-all fallback route for everything else

Each route is **stateless**, meaning the logic is evaluated per transaction, not stored across sessions.

***

### Design Considerations

The Routes Engine is designed to be:

| Feature              | Benefit                                                 |
| -------------------- | ------------------------------------------------------- |
| Stateless evaluation | Easier caching, fewer bugs, no cross-transaction memory |
| Conflict-checked     | Users can’t create overlapping or ambiguous routes      |
| Composable           | Works with future liquidity and swap modules            |
| Chain-agnostic       | Built to support new EVM chains and token standards     |
| User-scoped          | Routes are isolated per user to prevent collisions      |

***

### Future Plans:

* **Time-based logic** (route payments differently on weekdays vs weekends)
* **Geofenced rules** (based on sender location metadata)
* **Token splitting** (e.g. split $100: $80 to wallet A, $20 to wallet B)


---

# Agent Instructions: 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:

```
GET https://docs.reveel.id/core-services/routes-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.