Wallets

Each wallet's private key is encrypted with AES-256-GCM (random 96-bit IV per encryption, authenticated tag verified on every decrypt) under a 32-byte master key held only in the server environment (WALLET_ENCRYPTION_KEY). The plaintext key is never logged, never returned by any endpoint, and is decrypted transiently in-memory only to sign a send. If the master key is not configured, wallet creation and sends fail-closed — GullyPay never stores or signs with an unencrypted or absent key.

All wallet endpoints require a valid JWT or API key. Wallets are owned by the authenticated user.

{
"chain": "base"
}

Gully Chain Testnet wallets read and send over GULLY_CHAIN_RPC_URL (the public testnet RPC https://testnet-rpc.gullychain.xyz when unset). No stablecoin is built in there: USDC and glUSD are available once their contracts are set with USDC_TOKEN_GULLY_CHAIN_TESTNET / GLUSD_TOKEN_GULLY_CHAIN_TESTNET (decimals via USDC_DECIMALS_GULLY_CHAIN_TESTNET / GLUSD_DECIMALS_GULLY_CHAIN_TESTNET, default 6). Balances also list WETH and native ETH. Gasless sends and swaps are not available on Gully Chain. Testnet funds have no value.

{
"walletId": "…",
"chain": "base",
"address": "0x…",
"tokens": [
  { "token": "USDC", "raw": "12500000", "decimals": 6, "amount": "12.5", "amountCents": 1250 },
  { "token": "USDT", "raw": "0", "decimals": 6, "amount": "0", "amountCents": 0 }
],
"native": { "raw": "0", "decimals": 18, "amount": "0", "symbol": "ETH" }
}

{
"toAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD38",
"amount": 100.50,
"currency": "USDC"
}

{
"ledgerEntryId": "…",
"status": "submitted",
"txHash": "0x…",
"amount": 100.5,
"toAddress": "0x…",
"currency": "USDC",
"path": "eoa"
}

{
"ledgerEntryId": "…",
"status": "submitted",
"txHash": "0x…",
"amount": 100.5,
"toAddress": "0x…",
"currency": "USDC",
"path": "gasless",
"userOpHash": "0x…",
"smartAccountAddress": "0x…",
"sponsored": true
}

Sends are settled on-chain and are irreversible once confirmed. The returned txHash is the real broadcast hash — GullyPay never fabricates one. Validate the destination address before submitting.

The gasless rail moves tokens from the ERC-4337 smart account (smartAccountAddress in the response), which is a different address from the wallet's EOA (address). That smart account — not the EOA — must hold the tokens being sent. The two addresses are both controlled by the same encrypted owner key.

{
"walletId": "…",
"chain": "base",
"gaslessConfigured": true,
"smartAccountAddress": "0x…",
"balances": {
  "chain": "base",
  "address": "0x…",
  "tokens": [
    { "token": "USDC", "raw": "0", "decimals": 6, "amount": "0", "amountCents": 0 }
  ],
  "native": { "raw": "0", "decimals": 18, "amount": "0", "symbol": "ETH" }
}
}

Gasless is available on the same EVM chains as the EOA wallet — Base, Ethereum, and BSC — wherever a bundler URL is configured. Solana is settled through the dedicated Solana path, not ERC-4337. The EntryPoint (v0.6) and account factory are provided by the Coinbase Smart Account implementation; no entrypoint/factory address needs to be supplied.

{
"fromToken": "USDC",
"toToken": "USDT",
"amount": 500
}

{
"ledgerEntryId": "…",
"status": "submitted",
"txHash": "0x…",
"fromToken": "USDC",
"toToken": "USDT",
"amount": 500,
"sellAmount": "500000000",
"buyAmount": "499850000",
"price": "0.9997"
}

Swaps require a ZEROX_API_KEY (0x Swap API) configured on the server, and are only supported on the EVM chains 0x covers — Base, Ethereum, and BSC. If the key is not configured, or the wallet's chain is not supported by 0x, POST /wallets/:id/swap fails-closed with 503 Service Unavailable ("Token swap is not configured") and no ledger entry is written — it never returns a fabricated rate. Solana swaps are not yet supported (a documented follow-up, via Jupiter) and return a clear "not yet supported on Solana" error. glUSD is not on 0x, so it is not a valid swap token today.

The wallets described here are blockchain wallets. The Financial OS exposes a separate set of ledger-backed treasury wallets (POST /wallets, GET /wallets/me, GET /wallets/:id/ledger) for fiat + crypto double-entry accounting. See the Financial OS page.