Funding and withdrawals API

Use the Scalar reference for request schemas. All routes below start with /api/v1/wallets/{walletId} and require an owner account session or a key scoped to that wallet. Financial actions require withdraw permission and an Idempotency-Key. Never put a wallet private key into a funding request.

Discover routes and balancesCopy Anchor Link

• GET /balances: available HyperCore spot/perps and HyperEVM USDC. HyperEVM usdcRaw has 6 decimals.
• GET /funding: deterministic deposit proxy, token/spender, pending proxy USDC and the remaining deposit minimum.
• GET /funding/routes?chain=8453&search=USDC: source chains and tokens supported by Relay. Use chain=solana for Solana and direction=destination for withdrawal destinations.

Use returned chain IDs, token addresses and decimals. A chain in discovery does not guarantee every token pair or amount has a route; obtain a current quote. There is no promise to route to arbitrary unsupported networks.

Fund from an external EVM or Solana walletCopy Anchor Link

curl "$BASE/api/v1/wallets/$WALLET/funding/quote" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"chain":"8453","source":"0xYOUR_SOURCE_WALLET","token":"TOKEN_FROM_DISCOVERY","amountRaw":"20000000"}'

amountRaw is an integer in the source token's own decimals. The example is 20 tokens only for a 6-decimal token. Quote input never accepts an arbitrary destination: the backend binds it to this wallet's verified Papertrade deposit proxy.

The response contains quote, requestIds, and requiresSourceSignature:true. quote.raw.steps is Relay's provider payload. Execute the source transaction/signature steps using the Relay SDK or your own source-chain signer, validating the source chain, recipient, amount and expiry. The platform does not possess that external wallet's key. Signed source transactions are broadcast to that chain; Relay SDK execution uses Relay's documented endpoints, not a Paperterminal worker password/unlock command.

The minimum received amount plus existing pending proxy USDC must reach 10 USDC. Below-minimum quotes return deposit_below_minimum with the shortfall. Fees/slippage can change the required input.

Poll GET /funding/transfers/{requestId} for request IDs returned by this wallet's quote; another wallet's transfer ID is rejected. Then POST /funding/reconcile with {} checks trading credit. Relay delivery and spendable Papertrade balance are different stages. /funding reports remaining pending funds. Reconciliation does not send another deposit.

Fund from this terminal wallet's HyperEVM USDCCopy Anchor Link

curl "$BASE/api/v1/wallets/$WALLET/funding/hyperevm" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: deposit-unique-0001" -d '{"amount":"20"}'

The worker must have signing authorization and enough HyperEVM USDC/HYPE. It approves the verified deposit contract if needed, then deposits for this wallet's computed proxy. Transaction bytes/hash are durably checkpointed before broadcasting. Inspect command and history records after a timeout; never use a new idempotency key blindly.

Withdraw to an EVM chain or SolanaCopy Anchor Link

curl "$BASE/api/v1/wallets/$WALLET/withdrawals" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: withdraw-unique-0001" \
  -d '{"source":"trading","amount":"20","chainId":56,"token":"TOKEN_FROM_DISCOVERY","recipient":"0xYOUR_RECIPIENT"}'

amount is a USDC decimal string, at most 6 decimal places. source is trading (default), hypercore (existing spot USDC), or hyperevm (existing HyperEVM USDC). Existing-balance sources do not submit another Papertrade withdrawal. Trading withdrawals must be at least 10 USDC and cannot spend position margin. Existing-source transfers must be positive and satisfy the quote and network limits.

• Other EVM chains: use the discovered Relay chain ID, destination token and EVM recipient.
• Solana: chainId:792703809, discovered mint address and base58 recipient.
• Direct HyperEVM USDC: chainId:999, token 0xb88339cb7199b77e23db6e890353e22632ba630f, EVM recipient. This route does not use Relay.

The worker saves each phase and transaction receipt. GET /withdrawals returns progress, transaction hashes and Relay state. The initial command being completed means the worker handled the request, not that funds reached the destination.

For trading/Core sources, the existing gas policy may reserve part of the source amount for HYPE. The net delivered amount follows the saved quote; gas is not a platform profit fee. An existing HyperEVM source needs sufficient HYPE there. Pause copying and resolve conflicting transfers before a new withdrawal; the worker enforces balance and pending-operation checks.

Direct HyperCore operationsCopy Anchor Link

POST /withdrawals/hypercore with {"amount":"20"} withdraws trading USDC to the same wallet on HyperCore, without Relay or a HyperEVM leg. The backend encodes the protocol amount in 6 decimals, despite many other Papertrade amounts using 18.

POST /transfers/hypercore with {"amount":"20","recipient":"0x..."} sends existing available HyperCore USDC to another address on HyperCore. Both require withdraw scope and an idempotency key. This is not a cross-chain bridge.

Control an existing automatic withdrawalCopy Anchor Link

Use the saved withdrawal ID from /withdrawals:

• POST /withdrawals/{id}/pause with {} pauses automatic next steps; it does not cancel a broadcast transaction.
• .../resume resumes the saved flow.
• .../retry uses the existing corrected-retry rules and rejects unsafe replacements.
• .../gas and .../to-evm advance eligible Core steps manually.
• .../quote refreshes the delivery quote before its origin transfer.
• .../bridge with {"quoteId":"..."} executes that saved quote.

These require withdraw scope and separate operation idempotency keys. An ambiguous transaction keeps its original hash/nonce. The worker does not assume failure just because a provider timed out.

Direct HYPE or USDC on HyperEVMCopy Anchor Link

To send assets already held on HyperEVM, create a withdrawal with source: "hyperevm". This does not withdraw trading margin or move funds through HyperCore.

For HYPE, use sourceAsset: "HYPE", chainId: 999, token: "0x0000000000000000000000000000000000000000", the recipient address, and a decimal amount with up to 18 decimal places. For USDC, use sourceAsset: "USDC", the HyperEVM USDC token address, and up to six decimals. Leave HYPE in the wallet for network fees. Normal wallet ownership, withdrawal scope, and idempotency requirements apply.

In the funding UI, receive amounts and fees update automatically after you pause typing. These estimates do not create withdrawals. Quotes refresh before execution; trading-source gas purchases can reduce the final amount available to bridge. Deposit progress distinguishes wallet submission, Relay delivery, and trading credit, with expandable explorer receipts.

Funds received directly by the walletCopy Anchor Link

The wallet has the same EVM address across supported networks. Receiving a token on Base, Ethereum, HyperEVM, or another EVM chain does not credit Papertrade. The funds remain on that chain until transferred. Do not send Solana-native assets to an EVM address.

Open Fund account. The Receive tab shows the wallet address and the tokens the wallet holds on the selected network. The Bridge & swap tab quotes a bridge or swap to the same wallet and shows source-chain gas. Balances are read with one Multicall3 call per network. Networks without Multicall3 use individual reads, and a balance that cannot be read shows as unavailable, not zero. Review the output and minimum received before confirming. The worker only supports Relay's exact native/ERC20 deposit routes; permit, multicall and other contract paths are rejected. Native gas is required on the source chain. Provider support and liquidity determine route availability.

For automation, use the wallet-scoped REST endpoints (the POST endpoints require withdraw scope and an Idempotency-Key):

• POST /api/v1/wallets/{walletId}/wallet-funds/balance: { "chainId": 8453, "tokenAddress": "0x0000000000000000000000000000000000000000" }.
• POST /api/v1/wallets/{walletId}/wallet-funds/quote: supply originChain, destinationChain, token, destinationToken, and integer amountRaw in source-token decimals.
• POST /api/v1/wallets/{walletId}/wallet-funds/execute: { "quoteId": "saved-quote-uuid" }. This authorizes the saved quote, not arbitrary transaction calldata.
• GET /api/v1/wallets/{walletId}/wallet-funds: tracked transfers with source and destination hashes. executing and bridging are pending; only delivered indicates Relay-confirmed delivery.

Signed bytes are saved privately before broadcast and the same hash is reconciled after restart. An uncertain response must not be retried as a fresh bridge. The recipient is always the authenticated wallet. These routes do not send funds to third parties. Once USDC is on HyperEVM, use the existing funding endpoint to deposit it into Papertrade; trading credit remains a separate confirmation step.