DOCSIntegrate stablecoin liquidity
On this page
Connect an ERC20 already issued on GIWA to an Ammora pool and operate liquidity provision → trading → fee collection → withdrawal. You do not need to issue the token again or graduate a Launch. This guide uses the giwa-almm-unified-v1 profile on GIWA Sepolia (91342).
New issuer or treasury team? Start with the stablecoin team integration guide for responsibilities, required inputs, your first unsigned result, application screens and revenue accounting. It is also available as Markdown for your AI.
1. What do you provide and receive?
The issuer or LP supplies both ERC20 assets and gas ETH. Ammora provides pools, LP positions, swaps, and fee claims. It does not automatically fund liquidity or provide the issuer's fiat redemption, reserves, or mint authority. Available trade size and price impact depend on liquidity depth.
| Role | Provide | Authority or result |
|---|---|---|
| Issuer | Official GIWA asset addresses, decimals, and mint/pause/upgrade controls | Connect reviewed existing assets to a pool |
| LP operator | Both ERC20 assets, gas ETH, supply/withdrawal budgets | Manager NFT and LP principal management |
| feeOwner | Defaults to the LP wallet; may be configured separately | Claim, delegate, and revoke fee authority |
| feeDelegate (optional) | Execution wallet approved by feeOwner | Claim only the authorized fees |
| payout | Actual fee recipient address | Receive ERC20; separate from LP principal authority |
Trading fees are allocated to LP and protocol shares according to the selected pool's actual policy. When feeOwner or an authorized delegate claims LP fees, they are sent to the reviewed payout address. Principal withdrawal is a separate LP operation. Verify the split and amounts through pool/profile reads and claim results; do not assume a fixed return.
2. Install without signing in
Use SDK 0.3.8 together with the examples' source-pinned fee compatibility module. Do not assume that the functions in extensions/almm-unified/fee-claims-compat.ts are new exports of the public npm SDK.
Browse the ALMM planning code and its shared modules directly in Docs. For your own application, begin with the SDK quickstart and Markdown.
npm install --save-exact @ammora-protocol/sdk@0.3.8 viem
To run the complete CLI walkthrough, prepare the source project with local example setup. It includes the shared modules, JSON templates and unified:typecheck command; installing the SDK alone does not provide these files.
Next, configure the environment and plan/send functions in step 2 of the complete stablecoin walkthrough. Installation does not send transactions. Reads and plans need no private key. For an actual EOA send, supply the key to the process through a secure signer loader. Wallet-based web UIs should use the unsigned calldata.
3. Prepare the asset and operating manifest
Use the complete guide's generation command to create your manifest from src/stablecoin/manifests/native-issuer.template.json. Do not copy synthetic verification tokens, Ammora wallets, or existing NFTs from the profile.
- Record the official assets' chain, addresses, decimals, runtime code hashes, and evidence for proxy and authority review.
- Put the lower token address in base. Review raw budgets and the quote/base reference price in that same order.
- Assign the actual LP, feeOwner, delegate, and payout addresses.
- Set maximum inputs, slippage, price deviation, gas, TTL, and the observation time of an independent reference price.
- Do not change
pending/unreviewedtoreviewedwithout completing the checks. Replace template budgets such as1 rawwith reviewed values.
A name alone does not confirm official GIWA support for an issuer's asset, including FDUSD/cUSD. Do not mark unconfirmed tokens ready for integration. Do not assume support for fee-on-transfer, rebasing, unreviewed callbacks, or unreviewed proxy forms.
4. Follow the integration sequence
The complete walkthrough provides JSON inputs and copyable commands for each operation. Create a plan with plan OPERATION REQUEST OUTPUT, review caller, target, amounts, recipient, and reviewHash, then use send PLAN REVIEWED_HASH to execute one transaction at a time.
| Stage | Operation | Completion condition |
|---|---|---|
| Token policy | policy |
Verify the selected Factory→Registry binding and both asset policies |
| Register only when needed | register-approve, register |
Small round trip only for unclassified, non-owner-configured assets; registrationVerified:true and poolSupported:true |
| Find pool | discover |
Determine whether to reuse an existing pool or create a new one |
| Create only when needed | create → discover |
Reconfirm the actual address, pair, and fee after the receipt |
| Supply liquidity | approve → seed |
Check Manager approval, range, and caps; record the actual NFT ID |
| Trade | approve → swap |
Pool approval, quotes in both directions, minimum received, and actual balances |
| Inspect revenue | inspect |
Verify actual owner, feeOwner, and feePreview |
| Delegate fees | grant |
feeOwner fixes the delegate, payout, and expiry |
| Collect fees | claim |
Events, Transfers, and recipient balance changes agree |
| Close operations | revoke → remaining claim → exit → close |
Revoke authority, reconcile fees/principal, then close the empty NFT |
Do not register an already-supported token again. A permissionless probe must not overwrite Registry owner policy. If a pool already exists, do not send create. Approval targets are the Registry, Manager, or Pool for the particular operation, not FeeController.
5. Verify receipts and build the operator view
Show principal and fees separately. Verify fee receipt using RewardManager events, both assets' Transfers, and payout balance changes at the receipt block. A zero feePreview or a no-op plan is not a paid claim.
Keep the pair, pool, NFT ID, feeOwner, delegate expiry, payout, supplied amounts, current balances, cumulative receipts, and latest reconciliation hash in the operator view. A newly supplied position has a new NFT whose delegation must be checked. Issuer-admin or payout status does not grant LP claim authority.
Do not send concurrently from the same wallet. Reconcile any unknown hash or nonce journal first. If the reference price expires, or state, recipients, or amounts change, create and review a new plan.
6. Ask AI to build the integration UI
Use the downloadable AI prompt.
Read https://docs.ammora.org/llms.txt and https://docs.ammora.org/build/stablecoin.
Build a GIWA Sepolia stablecoin LP operator UI using STABLECOIN-QUICKSTART.md
and the extensions/almm-unified source files at https://docs.ammora.org/examples.
Use the example Markdown and linked dependencies; follow /guides/example-setup for local CLI commands.
Use SDK 0.3.8 with the giwa-almm-unified-v1 source compatibility module.
Implement policy reads, registration when needed, pool discovery, liquidity, swaps, fee inspection/delegation/claim, and withdrawal.
Start with manifest validation and read/unsigned-plan UI; add wallet signing after review.
Do not guess asset addresses, roles, prices, or budgets. Leave unconfirmed values as required user inputs.
Distinguish LP principal authority, feeOwner, feeDelegate, and payout; explain authority failures.
Before signing, display calldata, amounts, approval targets, payout, minimum received, and expiry.
Implement a transaction journal and receipt reconciliation, including actual amounts received after a fee claim.
Do not assume automatic migration of existing v3/v4 pool positions.
Never store private keys in the browser. Distinguish passing tests from verified live transactions.
7. Distinguish other liquidity paths
Do not apply this unified profile's 1bp example to the entire default SDK catalog. Default ALMM and ARL paths have separate deployment and fee conditions. Compare the path selection guide, default catalog integration, and ALMM unified guide. Automatic migration of existing Uniswap v3/v4 positions and guaranteed 1:1 prices for all assets are not included.