> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zet.money/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand the building blocks of the Zet API

# Core Concepts

## Smart Wallets

Every Zet-managed wallet is an ERC-4337 compliant smart contract wallet that lives on-chain.

### Why smart accounts?

| Feature            | EOA (Traditional)             | Smart Account                      |
| ------------------ | ----------------------------- | ---------------------------------- |
| Gas payment        | User pays gas in native token | **Sponsored by Zet** (gasless)     |
| Multi-chain        | Different address per chain   | **Same address on all EVM chains** |
| Batch transactions | One tx at a time              | **Multiple ops in one tx**         |
| Recovery           | Lost key = lost funds         | Programmable recovery              |
| Upgradeability     | None                          | **Modular, upgradeable**           |

### Deterministic addresses

When you create a wallet via the Zet API, the address is derived deterministically from the same factory contract, salt, and owner. This means:

* The wallet address is **identical on Base, BSC, and all supported EVM chains**
* No separate deployment step per chain — **lazy deployment** happens on first use
* You can show users a single address for all chains

### Gas sponsorship

Zet sponsors gas for all transactions executed through Zet-managed wallets. Your users never need to hold native tokens (ETH, BNB) for gas.

## Custodial vs Non-Custodial

Zet supports both integration models:

### Custodial (Zet-managed wallets)

Use `walletId` in your API calls. Zet handles everything:

```json theme={null}
{
  "quoteId": "qt_01H8X3...",
  "walletId": "wal_01H8X3..."
}
```

* Zet creates and manages the wallet
* Transactions are signed and broadcast automatically
* Gas is sponsored — zero native token balance needed
* Best for: fintech apps, neobanks, custodial exchanges

### Non-Custodial (bring your own wallet)

Use `sourceAddress` / `destinationAddress` in your API calls. Zet returns transaction data for the user to sign:

```json theme={null}
{
  "quoteId": "qt_01H8X3...",
  "sourceAddress": "0xabc..."
}
```

* User controls their own wallet and keys
* Zet returns unsigned transaction data (`approvalData`, `transactionData`)
* User must sign and broadcast transactions themselves
* Gas paid by the user
* Best for: DeFi apps, self-custody wallets, advanced users

## Transaction lifecycle

Every transaction follows the same lifecycle:

```
Quote → Initiate/Execute → Pending → Completed/Failed
```

<Steps>
  <Step title="Quote">
    Request a price quote. Includes fees, rates, and estimated output. Valid for \~5 minutes.
  </Step>

  <Step title="Initiate / Execute">
    Submit the quote ID to start the transaction. For ramps, this returns deposit details. For swaps/transfers, execution begins immediately (custodial) or returns transaction data (non-custodial).
  </Step>

  <Step title="Pending">
    The transaction is in progress. For on-ramps, waiting for user's bank transfer. For swaps, the route is being executed on-chain.
  </Step>

  <Step title="Completed / Failed">
    Terminal state. On completion, crypto is delivered and webhook fires. On failure, an `errorMessage` explains what went wrong.
  </Step>
</Steps>

<Info>
  Use **webhooks** for production to receive real-time status updates. Polling (`GET /onramp/{id}`) is available but webhooks are more efficient and reliable.
</Info>

## Fee structure

Zet charges transparent, predictable fees. All fees are included in the quote response — what you see is what you get.

### On-ramp (Buy crypto with NGN)

| Fee          | Amount              | Condition                   |
| ------------ | ------------------- | --------------------------- |
| Provider fee | 0.1% of CNGN amount | Capped at 200 NGN           |
| Platform fee | 50 NGN              | Always                      |
| Swap fee     | 50 NGN              | Only if target token ≠ CNGN |

### Off-ramp (Sell crypto for NGN)

| Fee          | Amount              | Condition                   |
| ------------ | ------------------- | --------------------------- |
| Platform fee | 50 NGN              | Always                      |
| Provider fee | 0.1% of fiat amount | Capped at 200 NGN           |
| Swap fee     | 50 NGN              | Only if source token ≠ CNGN |

### Swap

| Fee            | Amount            | Condition               |
| -------------- | ----------------- | ----------------------- |
| Platform fee   | 50 NGN equivalent | Always                  |
| DEX/Bridge fee | Variable          | Set by routing provider |

### Cross-chain transfer

| Fee          | Amount             | Condition              |
| ------------ | ------------------ | ---------------------- |
| Platform fee | 100 NGN equivalent | Always                 |
| Bridge fee   | Variable           | Set by bridge protocol |

<Note>
  Platform fees in NGN are converted to the source token at the current market rate and deducted from the transaction.
</Note>

## Routing

Swaps and cross-chain transfers are routed through Zet's multi-chain liquidity aggregator that finds the optimal path across:

* **DEXs**: Multiple decentralized exchanges
* **Bridges**: Multiple bridge protocols

The routing engine considers:

* Best price across all available paths
* Slippage tolerance (default: 0.3%)
* Gas costs on source and destination chains
* Bridge reliability and speed

## Idempotency

Use the `reference` field when initiating transactions to ensure idempotency. If you retry a request with the same `reference`, Zet returns the existing transaction instead of creating a duplicate.

```json theme={null}
{
  "quoteId": "qt_01H8X3...",
  "walletId": "wal_01H8X3...",
  "reference": "order_12345"
}
```