Swaps & Price

Who it's for: Users converting between cGHS and USDC — whether sending money, cashing out, or accessing a different currency for a purchase. Why it matters: Swaps route automatically through the best available liquidity source, so users always get a competitive rate without needing to understand how the market works underneath.

`POST /swap`

Execute a token swap through the Shika Liquidity Engine. The RouterHook fires automatically — P2P offer matching, JIT liquidity injection, and flash loan fallback all happen on-chain with no extra service calls.

SSI required: No — swaps are open to any wallet.

Request

{
  "userAddressId": "wallet-uuid",
  "userAddress": "0xabc...",
  "tokenIn": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "tokenOut": "0x3126627A607E730E3eCF9BbfFD67fa18Deaab846",
  "amountIn": "65000000",
  "minAmountOut": "980000000",
  "offerId": "5"
}

Field	Notes
`tokenIn` / `tokenOut`	Token addresses — service sorts to derive `token0/token1`
`amountIn`	Exact input, base units
`minAmountOut`	Slippage protection
`offerId`	Optional — targets a specific P2P offer via `hookData`

Response

{ "success": true, "txHash": "0xdeadbeef..." }

Swaps are fire-and-confirm — no D1 tracking.

`GET /swap/quote`

Off-chain output estimate for a given input.

GET /swap/quote?tokenIn=0x833...&tokenOut=0x312...&amountIn=65000000

Response

{
  "estimatedOut": "984000000",
  "priceImpactBps": 12,
  "currentPrice": "0.06823"
}

How the Hook Works

poolManager.swap(poolKey, params, hookData)
        ↓
RouterHook.beforeSwap() [automatic]
  1. Check P2POfferBook for matching offer
     → match: lock offer, inject P2P JIT at offer price
  2. No match + large swap (> threshold):
     → flash borrow from LendingPool, inject JIT at oracle price
  3. No match + small swap:
     → JITRebalancer shared pool fallback
Swap executes
RouterHook.afterSwap() [automatic]
  → remove JIT liquidity, repay flash loan, unlock offer

`GET /pool` — Default Pool State

{
  "sqrtPriceX96": "...",
  "currentTick": -27336,
  "liquidity": "...",
  "ghsUsdPrice": "0.065230",
  "lpFee": 100,
  "protocolFee": 0,
  "meta": { "token0": "0x3126...", "token1": "0x833..." }
}

Price Routes

GET /price/ghs
    → { answer, updatedAt, staleSince }
 
GET /price/ghs/sqrt?spreadBps=0
    → { sqrtPriceX96, tick }
 
GET /price/ghs/fixed?price=6500000
    → { sqrtPriceX96, tick }
 
GET /price/rwa/:routerAddress
    → { sqrtPriceX96, tick, oraclePrice, oracleUpdatedAt }
 
GET /price/rwa/:routerAddress/sqrt?spreadBps=0
    → { sqrtPriceX96, tick }

Admin — Pool Creation

Used when launching a new trading pair (e.g. RWA token / cGHS).

`GET /admin/pool/derive`

Preview pool parameters before creating.

GET /admin/pool/derive?rwaToken=0x...&pairedStablecoin=0x...&priceRouter=0x...
→ { token0, token1, initialSqrtPriceX96, impliedPrice, fee, tickSpacing, hooks, poolId }

`POST /admin/pool/create`

Requires x-admin-secret.

{
  "rwaToken": "0xrwa...",
  "pairedStablecoin": "0x3126627A607E730E3eCF9BbfFD67fa18Deaab846",
  "priceRouterAddress": "0xpricerouter...",
  "deployRebalancer": true
}

Response: { "id": "uuid", "status": "pending" } (202)

POST /swap

GET /swap/quote