> For the complete documentation index, see [llms.txt](https://docs.onre.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onre.finance/technical-resources/onre-smart-contract-integration.md).

# OnRe Smart Contract Integration

The OnRe program is the primary on-chain interface for ONyc market data, minting, liquidity, and redemptions on Solana.

New integrations should use the v2 instruction set. The legacy `take_offer` and `take_offer_permissionless` instructions remain callable for migration purposes but should not be used in new integrations.

### Quick Reference

| Property                                 | Value                                                                                                   |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Network                                  | Solana Mainnet                                                                                          |
| Program ID                               | `onreuGhHHgVzMWSkj2oQDLDtvvGvoepBPkqyaubFcwe`                                                           |
| ONyc mint                                | `5Y8NV33Vv7WbnLfq3zBcKSdYPrk7g2KoiQoe7M2tcxp5`                                                          |
| USDC mint                                | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`                                                          |
| USDG mint                                | `2u1tszSeqZ3qBWF3uNGPFc8TzMk2tdiwknnRMWGWjGWH`                                                          |
| MarketStats PDA                          | `BuPMet2URHuTVKSHpj32AjsXxHgdsqeA1i82dr1b4Mi5`                                                          |
| TypeScript client used by the repository | `@coral-xyz/anchor` 0.32.1                                                                              |
| Source                                   | [onre-finance/onre-sol](https://github.com/onre-finance/onre-sol)                                       |
| IDL                                      | [target/idl/onreapp.json](https://github.com/onre-finance/onre-sol/blob/master/target/idl/onreapp.json) |

Pin the IDL or repository commit used during integration, as account layouts and discriminators may differ between releases.

### Choose an Integration Path

| Need                                                    | Recommended Path                                                            |
| ------------------------------------------------------- | --------------------------------------------------------------------------- |
| Route ONyc trades alongside other venues                | Integrate through Titan                                                     |
| Read NAV, APY, supply or TVL                            | Read the global `MarketStats` PDA                                           |
| Mint ONyc directly without an approval message          | `take_offer_permissionless_v2`                                              |
| Execute an approval-capable direct offer                | `take_offer_v2`                                                             |
| Quote or execute immediate ONyc liquidity where enabled | `quote_swap_buy` / `open_swap_buy` and `quote_swap_sell` / `open_swap_sell` |
| Submit a primary redemption                             | `create_redemption_request`, then track fulfillment or cancellation         |

For most integrations, use Titan for routed execution and read `MarketStats` directly for accounting data. Integrate with the OnRe program directly when CPI composition or instruction-level control is required.

```mermaid
flowchart TD
    A["What does your integration need?"] -->|Market data| B[Read MarketStats]
    A -->|Routed execution| C[Titan]
    A -->|Direct permissionless mint| D[take_offer_permissionless_v2]
    A -->|Direct approval-capable offer| E[take_offer_v2]
    A -->|Immediate buy or sell| F[RFQ / Prop AMM]
    A -->|Primary redemption| G[Redemption request]
```

### Core Accounts

#### State

The global `State` PDA stores protocol-wide configuration, including the kill switch, canonical ONyc mint, `main_offer`, supply and per-operation mint limits, and protocol roles. `main_offer` is used for global market statistics and BUFFER accrual.

```tsx
const [statePda] = PublicKey.findProgramAddressSync(
  [Buffer.from("state")],
  programId
);
```

#### Offer

An `Offer` represents an ordered token pair. For example, a USDC-to-ONyc offer and an ONyc-to-USDC redemption market use separate accounts.

```tsx
const [offerPda] = PublicKey.findProgramAddressSync(
  [
    Buffer.from("offer"),
    tokenInMint.toBuffer(),
    tokenOutMint.toBuffer(),
  ],
  programId
);
```

The `Offer` account contains pricing vectors and route-specific configuration:

* `fee_basis_points` for the regular v2 path;
* `fee_basis_points_permissionless` for the permissionless v2 path;
* `needs_approval`;
* `allow_permissionless`;
* `disabled`.

Read route configuration directly from the `Offer` account rather than hard-coding fee rates or assuming the regular and permissionless routes use the same fee.

#### MarketStats

The global `MarketStats` PDA provides NAV, APY, circulating supply, and TVL. See [Onchain Market Data](/technical-resources/onchain-market-data.md) for account layout, freshness, and integration guidance.

### Permissionless Minting

Use `take_offer_permissionless_v2` to exchange a supported input asset for ONyc when the relevant offer allows permissionless execution.

#### Interface

| Property            | Value                                             |
| ------------------- | ------------------------------------------------- |
| Instruction         | `take_offer_permissionless_v2`                    |
| Discriminator       | `[250, 180, 68, 89, 124, 124, 31, 250]`           |
| Argument            | `token_in_amount: u64`                            |
| Approval message    | None; it is not part of this instruction          |
| Instructions sysvar | Not part of this instruction                      |
| Fee field           | `offer.fee_basis_points_permissionless`           |
| Fee vault           | `configurable_vault` • `permissionless_offer_fee` |

`token_in_amount` includes the route fee and is expressed in the input mint's base units.

```tsx
import { BN } from "@coral-xyz/anchor";

const signature = await program.methods
  .takeOfferPermissionlessV2(new BN(tokenInAmount.toString()))
  .accountsStrict(accounts)
  .rpc();
```

#### Accounts

The v5 instruction layout contains 32 accounts across the following groups:

| Group             | Accounts                                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| Offer routing     | `offer`, `state`, offer vault authority and token accounts, permissionless authority and token accounts |
| User and mints    | input/output mints and token programs, user input/output token accounts, user signer                    |
| Redemption refill | reverse-direction `redemption_offer`, redemption vault authority and input-asset token account          |
| Accounting        | `offer_proceeds` configurable vault and ATA; `permissionless_offer_fee` configurable vault and ATA      |
| BUFFER            | `buffer_state`, reserve ONyc ATA, management-fee ONyc ATA, performance-fee ONyc ATA                     |
| Market data       | `market_stats`, circulating-supply excluded-balance PDA, `state.main_offer`                             |
| Programs          | Associated Token Program and System Program                                                             |

Valid ATAs and configurable-vault PDAs may be initialized during execution, with the user as payer.

#### Execution Flow

```mermaid
sequenceDiagram
    participant U as User
    participant P as OnRe program
    participant F as Permissionless fee vault
    participant R as Redemption vault
    participant O as Offer proceeds vault
    participant M as MarketStats

    U->>P: token_in_amount
    P->>F: permissionless route fee
    alt Redemption vault is below target
        P->>R: refill up to target
        P->>O: remaining net input
    else No refill headroom
        P->>O: net input
    end
    P-->>U: ONyc output
    P->>M: refresh canonical market snapshot
```

When the program controls the ONyc mint, it can mint the output directly. Otherwise, the output must be available in the offer vault. The v2 path also settles BUFFER accrual before a relevant change in ONyc supply.

#### Preflight Checks

Before submitting:

1. Fetch `State` and verify `is_killed` is false.
2. Fetch the `Offer` and verify the ordered mints.
3. Verify `allow_permissionless` is true and `disabled` is false.
4. Verify an active pricing vector exists.
5. Read `fee_basis_points_permissionless`.
6. Use integer base units throughout.
7. Simulate the final transaction using a recent blockhash.

`take_offer_permissionless_v2` does not accept `minimum_out`. Integrations that require an on-chain output bound should use the RFQ/Prop AMM execution surface or an outer program that enforces the bound.

### Approval-Capable Execution

`take_offer_v2` supports the regular v2 execution path, including offers that require an off-chain approval message.

| Property            | Value                                                               |
| ------------------- | ------------------------------------------------------------------- |
| Instruction         | `take_offer_v2`                                                     |
| Discriminator       | `[203, 29, 22, 81, 189, 205, 210, 60]`                              |
| Arguments           | `token_in_amount: u64`, `approval_message: Option<ApprovalMessage>` |
| Instructions sysvar | Required                                                            |
| Fee field           | `offer.fee_basis_points`                                            |
| Fee vault           | `configurable_vault` • `offer_fee`                                  |

The regular and permissionless routes use separate fee fields and fee vaults. `take_offer_v2` uses `offer.fee_basis_points` and the `offer_fee` vault.

### Pricing

Offers contain up to ten pricing vectors. The active vector is the vector with the latest `start_time` that is not in the future. Price advances at discrete `price_fix_duration` intervals using compound APR growth.

Use the program's quote/view logic or repository implementation when calculating expected output rather than JavaScript floating-point arithmetic.

Scale reference:

* Price and NAV: 9 decimals
* APR/APY: `1_000_000 = 100%`
* Fees: `10_000 = 100%`

### Other Execution Surfaces

#### RFQ Liquidity

Enabled Prop AMM pairs support immediate quote and execution through:

`quote_swap_buy` / `open_swap_buy`\
`quote_swap_sell` / `open_swap_sell`

Execution accepts a caller-provided `minimum_out`. Pair availability depends on current configuration and liquidity. See [RFQ and Onchain Liquidity](/technical-resources/rfq-and-onchain-liquidity.md) for pricing, liquidity targets, and router integration.

#### Primary Redemptions

Primary redemption is request-based:

```
create_redemption_request
        → fulfill_redemption_request
        → request closes when fully fulfilled
```

Creating a redemption request locks ONyc in the redemption vault and creates an asynchronous claim. It does not return the settlement asset within the same transaction. Integrations that require immediate output should use an enabled immediate-liquidity route instead.

See [Redemptions](/for-capital-providers/redemptions.md) for the full request lifecycle.

### Operational States

Integrations should handle protocol controls as defined operational states:

| State                            | Program Error                       | Integration Behavior                                                         |
| -------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------- |
| Global kill switch active        | `KillSwitchActivated` (`6024`)      | Stop guarded writes, show execution as paused, continue reading market data. |
| Permissionless route not allowed | `PermissionlessNotAllowed` (`6025`) | Do not retry; choose an allowed route.                                       |
| Offer disabled                   | `OfferDisabled` (`6112`)            | Remove or pause this pair until re-enabled.                                  |
| Redemption offer disabled        | `RedemptionOfferDisabled` (`6113`)  | Stop request or sell execution for that redemption market.                   |
| No active pricing vector         | `NoActiveVector` (`6041`)           | Do not quote; wait for a valid vector or contact OnRe.                       |

Preserve the original program error in logs and monitoring. A global kill switch or targeted route disable should not be reported as insufficient balance unless the integrating interface cannot represent a more specific state.

### PDA Reference

All PDAs are derived from the OnRe program ID.

| Account                             | Seeds                                                                |
| ----------------------------------- | -------------------------------------------------------------------- |
| State                               | `state`                                                              |
| Offer                               | `offer`, `token_in_mint`, `token_out_mint`                           |
| MarketStats                         | `market_stats`                                                       |
| Offer vault authority               | `offer_vault_authority`                                              |
| Permissionless authority            | `permissionless-1`                                                   |
| Mint authority                      | `mint_authority`                                                     |
| Redemption offer                    | `redemption_offer`, `token_in_mint`, `token_out_mint`                |
| Redemption request                  | `redemption_request`, `redemption_offer`, little-endian `request_id` |
| Redemption vault authority          | `redemption_offer_vault_authority`                                   |
| BUFFER state                        | `buffer_state`                                                       |
| Reserve vault authority             | `reserve_vault_authority`                                            |
| Circulating-supply excluded balance | `circ_supply_excl_balance`                                           |
| Configurable vault                  | `configurable_vault`, route-specific suffix                          |
| Prop AMM pair state                 | `prop_amm_pair`, canonical offer                                     |

Relevant configurable-vault suffixes include:

* `offer_fee`
* `permissionless_offer_fee`
* `offer_proceeds`
* `redemption_fee`
* `prop_amm_buy_fee`
* `prop_amm_sell_fee`
* `prop_amm_proceeds`
* `management_fee`
* `performance_fee`

### Token Support

Most v2 token movement paths use the SPL Token interface and support classic SPL Token or Token-2022 mints. ONyc market-stat recomputation and redemption token-in setup require the classic SPL Token program.

Guarded paths reject Token-2022 mints with non-zero transfer fees when the transfer delta cannot be accounted for safely.

### Migration

Legacy integrations should migrate to the current interfaces:

| Deprecated                           | Replacement                                                     |
| ------------------------------------ | --------------------------------------------------------------- |
| `take_offer`                         | `take_offer_v2`                                                 |
| `take_offer_permissionless`          | `take_offer_permissionless_v2`                                  |
| `get_tvl`                            | `MarketStats.tvl` or `get_tvl_v2`                               |
| `get_circulating_supply`             | `MarketStats.circulating_supply` or `get_circulating_supply_v2` |
| API/oracle polling for canonical NAV | `MarketStats.nav`                                               |
| Legacy redemption fulfillment        | Request-based redemption instructions                           |


---

# 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.onre.finance/technical-resources/onre-smart-contract-integration.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.