> For the complete documentation index, see [llms.txt](https://docs.flap.sh/flap/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flap.sh/flap/developers/vault-developers/gift-vault-v2.md).

# Gift Vault V2

## Overview

Gift Vault V2 allows you to assign an X (Twitter) account as the **Gift Owner** for a token launched through `VaultPortal`. The gift owner can prove control of that X account and direct the vault's fee flow to any EVM address of their choice.

The core mechanism is:

1. **Assign Gift Owner**: The X account you specify becomes the gift owner for the vault.
2. **Accumulating Phase**: After launch, the vault first stays in `ACCUMULATING` mode and holds incoming native BNB fees.
3. **Flexible Beneficiary**: Once the gift owner proves control, the vault enters `STREAMING` mode and routes fees to the chosen EVM address.
4. **7-Day Grace Period**: If the gift owner does not take over within the grace period, the gift flow is closed.
5. **Fallback: Holder Dividends**: After timeout, the vault enters `DIVIDEND` mode and routes value to token holders.

Compared with the legacy [Gift Vault (FlapXVault)](/flap/developers/vault-developers/gift-vault.md), Gift Vault V2 mainly brings:

* two V2 product options
* a new vault lifecycle: `ACCUMULATING -> STREAMING -> DIVIDEND`
* new launch constraints for the V2 product line
* holder-dividend fallback instead of buyback & burn

> Important: `VaultPortal` here is **not** the same contract as the Flap Bonding Curve Protocol `Portal`.

## Legacy Gift Vault vs Gift Vault V2

The old `gift-vault.md` document is for the legacy Gift Vault flow. This document is for the new Gift Vault V2 product line.

For integrators, the practical differences are:

| Topic                   | Gift Vault V1              | Gift Vault V2                                                           |
| ----------------------- | -------------------------- | ----------------------------------------------------------------------- |
| Product options         | one legacy Gift Vault flow | two product options: `GiftV4VaultFactoryV2` and `GiftTaxVaultFactoryV2` |
| API integration         | existing API               | same API, request format, and response format as V1                     |
| Fee routing lifecycle   | legacy gift flow           | `ACCUMULATING -> STREAMING -> DIVIDEND`                                 |
| Timeout fallback        | buyback & burn             | holder dividends                                                        |
| What you need to update | legacy integration         | mainly factory selection and launch-parameter validation                |

So if you already support Gift Vault V1, the main work for V2 is not rewriting your API integration. The main work is choosing the correct V2 factory and respecting the V2 launch constraints.

## Network Details

### BNB Smart Chain Mainnet

* `GiftV4VaultFactoryV2`: `0x6909aD1822Ece349CDDAb98E6F62EeeD9fAa2e10`
* `GiftTaxVaultFactoryV2`: `0xFb7ccc4Fd09Da5b7016A18d51e227Af4ABE53f44`

### BNB Smart Chain Testnet

* `GiftV4VaultFactoryV2`: `0xaa00b4CeFeE8b4BF7D2E23C21ae82cfC9AFC9D67`
* `GiftTaxVaultFactoryV2`: `0x2eDD880AB36b07bD030BDa28A13c3E9148C11622`

## Product matrix

Gift Vault V2 has two product options. The difference is mainly the launch constraints of the selected factory.

### `GiftV4VaultFactoryV2`

Use this factory for the zero-tax Gift V4 product.

Launch constraints:

* `tokenVersion == TOKEN_V3_PERMIT`
* `quoteToken == address(0)`
* `buyTaxRate == 0`
* `sellTaxRate == 0`
* `dividendBps == 0`
* `dividendToken == address(0)`

### `GiftTaxVaultFactoryV2`

Use this factory for the taxed Gift product.

Launch constraints:

* `tokenVersion == TOKEN_TAXED_V3`
* `quoteToken == address(0)`
* `buyTaxRate == sellTaxRate`
* `buyTaxRate / sellTaxRate` must both be one of:
  * `100` (1%)
  * `200` (2%)
  * `300` (3%)
* `dividendBps == 0`
* `dividendToken == address(0)`

### Shared launch-time vault data

For both Gift Vault V2 product options, the only launch-time vault parameter is the gift owner's X handle.

## Lifecycle

Gift Vault V2 has three states:

### 1. `ACCUMULATING`

* initial state after deployment
* vault accepts native BNB fees from the token
* funds stay inside the vault
* waiting for a valid X proof to assign the streaming recipient

### 2. `STREAMING`

* entered after a valid `manageByProof()` call
* all accumulated BNB is flushed immediately to `streamingTarget`
* future BNB is forwarded to the same target on receipt
* the target can be updated again by a newer valid proof

### 3. `DIVIDEND`

* entered after `createdAt + timeoutPeriod` if streaming was never activated
* sticky once entered
* vault wraps native BNB into the dividend token (normally WBNB)
* vault deposits the wrapped balance into the token's Dividend contract for holders

Default timeout for newly created vaults is `7 days`, configurable at the factory level for future vaults.

## API compatibility with Gift Vault V1

`gift vault v1` and `gift vault v2` use the same API interface.

This means:

* the API endpoints are the same
* the request format is the same
* the response format is the same
* existing V1 API integration code can be reused for V2 directly

So if you have already integrated the API in [Gift Vault (FlapXVault)](/flap/developers/vault-developers/gift-vault.md), you do not need to change your request / response parsing logic for V2.

## What is different in V2

For API integrators, the main V2 differences are:

* the factory addresses are different
* there are now two V2 product options
* launch constraints are different depending on which product you choose
* the vault lifecycle is now `ACCUMULATING -> STREAMING -> DIVIDEND`
* the fallback behavior is holder dividends instead of buyback & burn

## Integration notes

When integrating Gift Vault V2, the main things you need to do are:

1. choose the correct Gift V2 factory address
2. launch through `VaultPortal`
3. pass the gift owner's `xHandle` in `vaultData`
4. keep using the same API request / response handling as V1
5. update your product selection logic to match the V2 launch constraints

### Launch data

For Gift Vault V2, the only launch-time vault parameter is the gift owner's X handle.

### Product selection

* use `GiftV4VaultFactoryV2` for the zero-tax Gift V4 product
* use `GiftTaxVaultFactoryV2` for the taxed Gift product

For `GiftTaxVaultFactoryV2`, buy tax and sell tax should use the same preset, and the supported presets are `1%`, `2%`, or `3%`.

## Summary

If you already support Gift Vault V1 API integration, then Gift Vault V2 is mainly a product / factory upgrade, not an API upgrade.

In most cases, you only need to:

* switch to the correct V2 factory address
* choose the correct V2 product type
* respect the new launch constraints
* keep the existing API request / response integration unchanged


---

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

```
GET https://docs.flap.sh/flap/developers/vault-developers/gift-vault-v2.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.