Getting Started

TL;DR: This guide walks you through connecting to XCCY, depositing margin, and opening your first position. You'll be trading Fixed Yield vs Variable Yield in under 10 minutes.

Prerequisites

Before you begin:

• Wallet with supported tokens

• Network set to Polygon

• Some POL for gas fees

Step 1: Connect Your Wallet

Supported Wallets

Wallet	Status
MetaMask	✓ Supported
WalletConnect	✓ Supported
Coinbase Wallet	✓ Supported
Rabby	✓ Supported

Network Configuration

Network: Polygon Mainnet
Chain ID: 137
RPC: https://polygon-rpc.com

Step 2: Approve Tokens

Before depositing, approve XCCY to use your tokens:

import { ethers } from "ethers";

const USDC = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359";
const COLLATERAL_ENGINE = "0x23E2DD3bB6e35162eB48d473d540764d5902BAe5";

// Approve USDC
const usdcContract = new ethers.Contract(USDC, ERC20_ABI, signer);
await usdcContract.approve(COLLATERAL_ENGINE, ethers.MaxUint256);

Note: You only need to approve once per token.

Step 3: Deposit Margin

Deposit collateral to your account:

const COLLATERAL_ENGINE_ABI = [
    "function updateAccountMargin(tuple(address,uint96,address) account, address token, int256 marginDelta) external"
];

const collateralEngine = new ethers.Contract(
    COLLATERAL_ENGINE, 
    COLLATERAL_ENGINE_ABI, 
    signer
);

// Your account ID
const account = {
    owner: await signer.getAddress(),
    id: 0,  // Sub-account 0 (default)
    isolatedMarginToken: ethers.ZeroAddress  // Cross-margin mode
};

// Deposit 1,000 USDC
const depositAmount = ethers.parseUnits("1000", 6);  // USDC has 6 decimals

await collateralEngine.updateAccountMargin(
    account,
    USDC,
    depositAmount  // Positive = deposit
);

console.log("Margin deposited!");

Step 4: Check Available Pools

Query available pools and their current Fixed Yield rates:

const VAMM_MANAGER = "0xe8FE9b71355B1701036671AD3c8F6dF585eb7eBd";

const VAMM_MANAGER_ABI = [
    "function getVAMMState(bytes32 poolId) view returns (int24 tick, uint160 sqrtPriceX96)"
];

const vammManager = new ethers.Contract(VAMM_MANAGER, VAMM_MANAGER_ABI, signer);

// Pool configuration (example)
const poolKey = {
    underlyingAsset: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",  // USDC
    compoundToken: "0xA4D94019934D8333Ef880ABFFbF2FDd611C762BD",    // aUSDC
    termStartTimestampWad: 1765928094999999999999999999n,
    termEndTimestampWad: 1768520094999999999999999999n,
    feeWad: 100000000000000n,  // 0.01%
    tickSpacing: 10
};

// Compute pool ID
const poolId = ethers.keccak256(ethers.AbiCoder.defaultAbiCoder().encode(
    ["address", "address", "uint256", "uint256", "uint256", "int24"],
    [poolKey.underlyingAsset, poolKey.compoundToken, poolKey.termStartTimestampWad, 
     poolKey.termEndTimestampWad, poolKey.feeWad, poolKey.tickSpacing]
));

// Get current state
const [tick, sqrtPriceX96] = await vammManager.getVAMMState(poolId);

// Convert tick to Fixed Yield percentage
const fixedYield = Math.pow(1.0001, Number(tick)) * 100;
console.log(`Current Fixed Yield: ${fixedYield.toFixed(2)}%`);

Step 5: Open Your First Position

Option A: Lock Fixed Yield (FY Position)

If you want guaranteed, predictable yield:

const MIN_SQRT_RATIO = 4295128739n;
const MIN_TICK = -887270;
const MAX_TICK = 887270;

const VAMM_SWAP_ABI = [
    "function swap((address,address,uint256,uint256,uint256,int24) key, (tuple(address,uint96,address) account, int256 amountSpecified, uint160 sqrtPriceLimitX96, int24 tickLower, int24 tickUpper) params) external returns (int256, int256, uint256, int256, uint256)"
];

const vammManager = new ethers.Contract(VAMM_MANAGER, VAMM_SWAP_ABI, signer);

// Lock Fixed Yield on 10,000 USDC notional
const notional = ethers.parseUnits("10000", 6);

const tx = await vammManager.swap(
    [
        poolKey.underlyingAsset,
        poolKey.compoundToken,
        poolKey.termStartTimestampWad,
        poolKey.termEndTimestampWad,
        poolKey.feeWad,
        poolKey.tickSpacing
    ],
    {
        account: [account.owner, account.id, account.isolatedMarginToken],
        amountSpecified: -notional,  // NEGATIVE = Lock Fixed Yield
        sqrtPriceLimitX96: MIN_SQRT_RATIO + 1n,
        tickLower: MIN_TICK,
        tickUpper: MAX_TICK
    }
);

await tx.wait();
console.log("FY position opened! You now have locked Fixed Yield.");

Option B: Trade Variable Yield (VY Position)

If you expect Variable Yield to rise:

const MAX_SQRT_RATIO = 1461446703485210103287273052203988822378723970342n;

// Get Variable Yield exposure on 10,000 USDC notional
const notional = ethers.parseUnits("10000", 6);

const tx = await vammManager.swap(
    [
        poolKey.underlyingAsset,
        poolKey.compoundToken,
        poolKey.termStartTimestampWad,
        poolKey.termEndTimestampWad,
        poolKey.feeWad,
        poolKey.tickSpacing
    ],
    {
        account: [account.owner, account.id, account.isolatedMarginToken],
        amountSpecified: notional,  // POSITIVE = Trade Variable Yield
        sqrtPriceLimitX96: MAX_SQRT_RATIO - 1n,
        tickLower: MIN_TICK,
        tickUpper: MAX_TICK
    }
);

await tx.wait();
console.log("VY position opened! You now have Variable Yield exposure.");

Step 6: Monitor Your Position

Check Margin Balance

// Read your margin balance
const balance = await collateralEngine.getAccountMargin(account, USDC);
console.log(`USDC Margin: ${ethers.formatUnits(balance, 6)}`);

Check Position Health

// Get margin requirement
const marginReq = await collateralEngine.checkMarginRequirement(account);
console.log(`Margin Requirement: ${ethers.formatUnits(marginReq, 6)} USDC`);

Step 7: At Maturity — Settle

When the pool reaches maturity, settle your position:

const SETTLE_ABI = [
    "function settlePosition(tuple(address,uint96,address) account, tuple(address,address,uint256,uint256,uint256,int24) poolKey) external"
];

const collateralEngine = new ethers.Contract(
    COLLATERAL_ENGINE, 
    SETTLE_ABI, 
    signer
);

// After maturity date
await collateralEngine.settlePosition(
    account,
    poolKey
);

console.log("Position settled! Check your margin balance for PnL.");

Quick Reference

Contract Addresses (Polygon)

Contract	Address
VAMMManager	0xe8FE9b71355B1701036671AD3c8F6dF585eb7eBd
CollateralEngine	0x23E2DD3bB6e35162eB48d473d540764d5902BAe5
OracleHub	0x7a5084DEc5Fd89Ee1079005cE9cEa094c2A66E8E
AprOracle	0xA192144F89edC9fBB3D225856FaF284d9287EDb8
USDC	0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
aUSDC	0xA4D94019934D8333Ef880ABFFbF2FDd611C762BD

Key Constants

const MIN_TICK = -887270;
const MAX_TICK = 887270;
const MIN_SQRT_RATIO = 4295128739n;
const MAX_SQRT_RATIO = 1461446703485210103287273052203988822378723970342n;

Troubleshooting

"Insufficient margin"

You need more collateral. Deposit additional margin:

await collateralEngine.updateAccountMargin(account, USDC, additionalAmount);

"Pool expired"

The pool has reached maturity. You can only settle, not open new positions.

"Unauthorized"

Make sure you're calling from the account owner's wallet.

Next Steps

• Lock Fixed Yield — Detailed FY guide

• Trade Variable Yield — Detailed VY guide

• Provide Liquidity — Become an LP