# Allocrypt
> Non-custodial yield allocation on Monad (chain 143).

## Overview

Allocrypt is a non-custodial portfolio router for Monad. It routes capital across multiple yield-generating DeFi protocols in a single transaction. Users keep their vault tokens directly — no managed vaults, no intermediary tokens, no admin keys over funds.

When you deposit through Allocrypt, the PortfolioRouter pulls your tokens, swaps via 0x if needed, and deposits the full per-leg asset amount into external vaults. The router briefly receives the resulting vault shares, sends 0.49% of those shares to the protocol treasury, and forwards the remainder to your wallet.
For swapped legs, swap input sizing and minBuyAmount checks still use the full post-swap asset output. minSharesOut is checked against the gross shares minted by the external vault before the treasury share transfer.

## Contract Addresses (Monad, chain 143)

  - PortfolioRouter: 0xa0b681068be0109637cd3210c8739f153d27122d
  - PortfolioLens: 0x74b1ae4ac9b32fb13df0625cc587c2e8f2ef1605
  - AllocatorFactory: 0x04c220058dfe830516a727b2f90001fcad747931

## Supported Vaults

  - euler-usdc: Euler Earn USDC
    token: 0xA981f053C118FE4dB0e1aEBA192AAD20Ec7F7801
    asset: USDC (0x754704Bc059F8C67012fEd69BC8A327a5aafb603, 6 decimals)
    vaultType: ERC4626
  - upshift-ausd: Upshift earnAUSD
    token: 0x103222f020e98Bba0AD9809A011FDF8e6F067496 (deposit via 0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA)
    asset: AUSD (0x00000000eFE302BEAA2b3e6e1b18d08D69a9012a, 6 decimals)
    vaultType: UPSHIFT
  - kintsu-smon: Kintsu sMON
    token: 0xA3227C5969757783154C60bF0bC1944180ed81B9
    asset: WMON (0x3bd359C1119dA7Da1D913D1C4D2B7c461115433A, 18 decimals)
    vaultType: KINTSU
  - apriori-aprmon: aPriori aprMON
    token: 0x0c65A0BC65a5D819235B71F554D210D3F80E0852
    asset: WMON (0x3bd359C1119dA7Da1D913D1C4D2B7c461115433A, 18 decimals)
    vaultType: APRIORI
  - steakhouse-eth: Steakhouse Prime ETH
    token: 0xbeef04b01e0275D4ac2e2986256BB14E3Ff6ef42
    asset: WETH (0xEE8c0E9f1BFFb4Eb878d8f15f368A02a35481242, 18 decimals)
    vaultType: ERC4626
  - steakhouse-cbbtc: Steakhouse High Yield cbBTC
    token: 0xbeeff421948cDE29644a63FBA4ef5e5a621075d0
    asset: cbBTC (0xd18B7EC58Cdf4876f6AFebd3Ed1730e4Ce10414b, 8 decimals)
    vaultType: ERC4626

## Risk Personas (5)

  - the-anchor: Conservative — euler-usdc=48%, upshift-ausd=27%, steakhouse-eth=10%, kintsu-smon=8%, apriori-aprmon=7%
  - the-accumulator: Moderate — euler-usdc=28%, upshift-ausd=22%, steakhouse-eth=12%, kintsu-smon=19%, apriori-aprmon=19%
  - the-optimizer: Moderate-Aggressive — euler-usdc=15%, upshift-ausd=15%, steakhouse-eth=10%, kintsu-smon=30%, apriori-aprmon=30%
  - the-protocol-native: Aggressive — euler-usdc=6%, upshift-ausd=6%, steakhouse-eth=8%, kintsu-smon=40%, apriori-aprmon=40%
  - the-degen-architect: Max Risk — euler-usdc=3%, upshift-ausd=2%, steakhouse-eth=5%, kintsu-smon=45%, apriori-aprmon=45%

## API Endpoints

All endpoints are under https://www.allocrypt.xyz/api/ai/

### GET /api/ai/vaults

Returns all supported vaults with live APY data, asset details, risk personas, and contract addresses. Public, cached 5 minutes.

Response shape:
  {
    chainId: 143,
    network: "monad",
    router: "0x...",
    lens: "0x...",
    vaults: [{ slug, name, asset, assetAddress, assetDecimals, token, vaultType, description, yield: { baseApyBps, incentiveApyBps, totalApyBps, asOf } }],
    personas: [{ id, riskLabel, liquidityNote, vaults: { slug: pct } }]
  }

### GET /api/ai/portfolio/:address

Returns current positions and USD valuations for any Ethereum address. Public.

Response shape:
  {
    address, chainId: 143,
    totalUsdValue: "...",
    totalUsdValueFormatted: "...",
    positions: [{ vault, slug, name, asset, assetSymbol, shares, assetAmount, usdValue, usdValueFormatted, pricePublishTime }],
    allPositions: [...]
  }

Returns 400 for invalid address.

### POST /api/ai/allocate (x402-gated, $0.25 USDC)

Deploys a PersonalAllocator contract for a beneficiary. One per beneficiary — if already deployed, returns existing address without charging.

Request body:
  {
    "beneficiary": "0xYourWallet",
    "allocation": {
      "euler-usdc": 30,
      "upshift-ausd": 20,
      "steakhouse-eth": 15,
      "kintsu-smon": 20,
      "apriori-aprmon": 15
    }
  }

  - allocation values are percentages and must sum to 100.
  - Valid vault slugs: euler-usdc, upshift-ausd, kintsu-smon, apriori-aprmon, steakhouse-eth, steakhouse-cbbtc

Payment flow (x402):
  1. POST without X-Payment header → 402 response with payment requirements
  2. The 402 body contains: token (USDC), amount (250000 = $0.25), recipient (treasury address)
  3. Transfer the specified USDC amount to the treasury on Monad (chain 143)
  4. Retry the POST with header: X-Payment: {"txHash":"0x...","chainId":143}
  5. On success → 200 with deployed allocator address

Success response:
  {
    success: true,
    allocator: "0xDeployedAllocator",
    beneficiary: "0xYourWallet",
    deployTxHash: "0x...",
    blockNumber: 12345,
    chainId: 143,
    defaultAllocation: [{ slug, name, vault, vaultType, pct }],
    fee: "0.49% per PortfolioRouter leg, taken in vault shares after the external vault deposit and sent to protocol treasury"
  }

Already-deployed response (no payment needed):
  { success: true, allocator: "0x...", beneficiary: "0x...", alreadyDeployed: true }

### POST /api/ai/quote

Generates deposit calldata for a PersonalAllocator. Public, no authentication.

Request body:
  {
    "allocator": "0xDeployedAllocator",
    "grossAmount": "1000000000",
    "inputToken": "USDC",
    "allocation": {
      "euler-usdc": 30,
      "upshift-ausd": 20,
      "steakhouse-eth": 15,
      "kintsu-smon": 20,
      "apriori-aprmon": 15
    }
  }

  - grossAmount is in the input token's smallest unit (e.g. 1000000000 = 1000 USDC)
  - allocation percentages must sum to 100

Response:
  {
    allocator, grossAmount, feeBps: 49,
    approveAmount, approveToken, calldata: "0x...",
    nativeValue, deadline, expiresAt (unix ms number),
    summary: [{ vault, name, vaultType, depositAmount, estimatedShares, estimatedFeeShares, estimatedNetShares, depositAsset, needsSwap, feeTiming }],
    note: "The calldata has receiver set to address(0). Replace with the allocator's beneficiary address..."
  }

## PersonalAllocator Contract

Each agent gets their own on-chain contract deployed via AllocatorFactory:
  - Immutable beneficiary — the beneficiary always receives the net vault shares from each deposit
  - No allocator fee — PersonalAllocator forwards the full requested amount to PortfolioRouter
  - Default allocation — pre-configured split, adjustable by beneficiary only
  - No admin keys — no one can change the beneficiary, router, or treasury

Functions:
  deposit(DepositRequest)             // anyone can call — router deposits, then splits vault shares downstream
  setDefaultAllocation(VaultAlloc[])  // only beneficiary
  getDefaultAllocation()              // view
  beneficiary()                       // view — immutable beneficiary address
  router()                            // view — PortfolioRouter address
  treasury()                          // view — protocol treasury address

## Full Agent Flow

1. GET /api/ai/vaults — discover available vaults, APYs, and risk personas
2. POST /api/ai/allocate — deploy your allocator (x402: transfer $0.25 USDC to treasury, retry with X-Payment header)
3. POST /api/ai/quote — get deposit calldata plus per-leg gross/net vault share estimates
4. Approve grossAmount of input token to your allocator contract address
5. Call allocator.deposit() with the calldata from the quote
6. GET /api/ai/portfolio/:address — verify your positions

## Docs Pages

  - https://www.allocrypt.xyz/docs — Overview, supported protocols, how it works
  - https://www.allocrypt.xyz/docs/contracts — Contract architecture, all addresses, vault types
  - https://www.allocrypt.xyz/docs/ai-skills — AI API reference, x402 flow, PersonalAllocator details