For the complete documentation index, see llms.txt. This page is also available as Markdown.

Gift Vault

Overview

The Gift Vault lets you assign an X (Twitter) account as the Gift Owner for a token. The gift owner can prove control of that X account and direct the vault's fee flow to any EVM address of their choice β€” and change that address anytime by presenting a new proof.

You can use it as a way to give tax fee to an X user, or build more interesting use cases on top of it. It makes it easier for a web2 developer or an agent to manage tax fee routing through social proof. Some ideas:

  • Create an X account for an agent and launch a tax token that assigns the agent as the gift owner. The agent routes the tax fee to any EVM address, accepting funding requests via tweets. This could work as charity funds or a VC that supports new projects.

  • A social game where players tweet to a game X account and get the tax fee routed to their address based on social tasks or achievements.

This page documents the current Gift Vault V2 product line, which is what new integrations should target. The legacy Gift Vault V1 (FlapXVault) is documented in the Appendix: Gift Vault V1 (legacy) at the end of this page β€” the API integration is identical between versions, so if you already support V1 you mainly need to read the "What's different in V2" section.

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 while 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. Default timeout is 7 days, configurable at the factory level for future vaults.

  • Sticky once entered.

  • Vault wraps native BNB into the dividend token (normally WBNB) and deposits the wrapped balance into the token's Dividend contract for holders.

This is a change from Gift Vault V1, whose grace-period fallback was buyback & burn instead of holder dividends. See the Appendix for the V1 lifecycle.

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.

API integration guide

Gift Vault V2 uses the exact same off-chain API as the legacy Gift Vault V1 β€” the endpoints, request format, and response format are unchanged. If you already have a working V1 integration, you can reuse it as-is; the only thing that changes for V2 is the factory address and the on-chain launch constraints (product matrix above).

The mechanism, end to end:

  1. Assign Gift Owner β€” the X account you specify becomes the gift owner who controls where fees go.

  2. 7-Day Grace Period β€” if the gift owner doesn't manage the fees at least once within the timeout, control is forfeited to the fallback (holder dividends for V2, buyback & burn for legacy V1).

Step 1: Parse and validate tweet content

Integrators must fetch the tweet themselves. The tweet format is strictly enforced:

Tweet Format: gift the fee from [tax_token_address] to [target_address] #FlapGift

Step 2: ⚠️ MANDATORY PREFLIGHT CHECK

Always call canManageVault() on-chain before submitting to the backend. The backend is rate-limited to 1 request per minute per IP, and skipping this step risks an IP ban on rejected requests.

Step 3: Submit to backend API

Only call if Step 2 passed. Rate limit: 1 request per minute per IP; violating may result in an IP ban.

Endpoint: POST {relayerEndpoint}/submit

Step 4: Poll for on-chain confirmation

The relayer processes transactions asynchronously and does not return a transaction hash β€” poll canManageVault to confirm success. Once processed, canManageVault returns false with error "The tweet is outdated", which signals success.

Manual submission fallback

If the backend relayer times out after 60 seconds, you can submit the proof directly on-chain using the proof data returned from the backend:

canManageVault() reference

Parameters: taxToken (address), xHandle (string, must be lowercase), tweetId (uint128)

Returns: canManage (bool), errorMessage (string)

Possible error messages:

Error Message
Meaning

"GiftVaultV2 not found for this tax token"

No vault exists

"xHandle does not match"

Wrong X handle

"Vault is already in dividend mode"

Vault cannot be managed anymore

"The tweet is outdated"

Tweet already used (success!)

"" (empty string)

Can manage (success)

Error handling summary

Error
Cause
Solution

"Tweet is not valid"

Deleted/suspended

Use valid, active tweet

"Tweet has no text"

Media-only tweet

Ensure text content

"Author mismatch"

Wrong X handle

Verify correct user

"Format mismatch"

Incorrect format

Use exact format

"Token mismatch"

Wrong address

Verify addresses match

"Vault not found"

No vault exists

Check token has a vault

"xHandle does not match"

Wrong vault owner

Use correct X handle

"Vault is already in dividend mode"

Timed out / locked

Cannot manage anymore

"Tweet is outdated"

Already used (success)

Use new tweet ID for the next update

Rate limit error

Too many requests

Wait 60 seconds

Network timeout

Backend slow

Retry later

Summary checklist

  1. Fetch the tweet yourself.

  2. Validate tweet content (author, format, tax token match).

  3. ⚠️ MANDATORY: call canManageVault(). If false, stop β€” do not call the backend.

  4. Submit to backend (only if preflight passed; rate limited to 1/min).

  5. Poll canManageVault() every 15s for up to 60s. Success = error "The tweet is outdated".

  6. Implement timeouts and the manual submission fallback.

Appendix: Gift Vault V1 (legacy)

This section documents the original Gift Vault (FlapXVault), kept for integrators who still support the legacy factory. New integrations should use Gift Vault V2 (documented above) β€” the API integration mechanics above apply unchanged to V1; only the factory address, states, and fallback differ.

V1 vs V2 summary

Topic
Gift Vault V1
Gift Vault V2

Product options

one legacy Gift Vault flow

two product options: GiftV4VaultFactoryV2 and GiftTaxVaultFactoryV2

API integration

same API as V2

same API, request format, and response format as V1

Fee routing lifecycle

ACCUMULATING -> STREAMING -> FALLBACK_SNOWBALL

ACCUMULATING -> STREAMING -> DIVIDEND

Timeout fallback

buyback & burn

holder dividends

V1 lifecycle

  1. Assign Gift Owner β€” the X account you specify becomes the gift owner who controls where fees go.

  2. Flexible Beneficiary β€” the gift owner can assign fees to any EVM address and change it anytime.

  3. 7-Day Grace Period β€” if the gift owner doesn't manage the fees at least once in the first 7 days, control is forfeited.

  4. Fallback: Buyback & Burn β€” if control is forfeited, fees are automatically used for buyback and burn.

V1 Network Details

BNB Smart Chain Mainnet

  • Gift Vault Factory: 0x025549F52B03cF36f9e1a337c02d3AA7Af66ab32

  • Relayer API Endpoint: https://bnb-x-relayer.taxed.fun/submit

BNB Smart Chain Testnet

  • Gift Vault Factory: 0xa02DA44D67DB6D692efa7f751b5952bd670d5326

  • Relayer API Endpoint: https://bnbtest-x-relayer.taxed.fun/submit

V1 Gift Vault interface (IFlapXVault)

Last updated