> ## Documentation Index > Fetch the complete documentation index at: https://docs.groundtech.co/llms.txt > Use this file to discover all available pages before exploring further. # Agentic Installation > Copy-paste prompts that guide an AI coding agent through a complete Ground Portfolio Wallets integration, tailored to your product type. Use the prompts below to have an AI coding agent (Claude, Cursor, Copilot, etc.) integrate Ground's Portfolio Wallets API into your product. Each prompt is tailored to a specific customer type so the agent optimizes for your product's goals. **How it works:** Each prompt runs a multi-step process. The agent will first analyze your codebase and ask clarifying questions before writing any code. This avoids hallucinations from incorrect assumptions about your stack, infrastructure, or architecture. These prompts are designed for use against the **sandbox** environment (`https://sandbox.groundtech.co`). Do not point at production until you have validated the integration end-to-end in sandbox. ## Prerequisites Before running any prompt, make sure you have: 1. A Ground sandbox API token (contact your Ground rep if you don't have one) 2. Your AI coding agent has access to your project's codebase 3. Access to [Ground's API documentation](https://docs.groundtech.co) *** ## Neobank / Savings Product Use this if you are building a consumer or business banking product where end-users hold balances and expect to earn yield on idle funds. ```text Step 1: Discovery & Planning theme={"theme":{"light":"github-light","dark":"github-dark"}} You are integrating Ground's Portfolio Wallets API into our product. Ground is a yield infrastructure provider -- their Portfolio Wallets API lets us allocate customer stablecoin deposits across multiple yield sources (e.g. overcollateralized lending, delta-neutral strategies, stablecoin yield tokens) via a single REST API. Ground handles allocation, rebalancing, withdrawals, and reporting. We are a neobank / savings product. Our goal is to offer yield on customer deposits with these priorities: - Capital preservation and liquidity (customers expect to withdraw at any time) - Transparent yield display (earned amounts, current APY) - Webhook-driven architecture so our UI updates in real time Before writing any code, do the following: 1. Read our existing codebase to understand: - What language/framework we use for our backend - How we currently handle user accounts and balances - How we process deposits and withdrawals today - Whether we have an existing webhook ingestion system - How we store secrets and API credentials - What database we use and how we manage migrations 2. Read Ground's API documentation using the specific links below: - API conventions (auth, pagination, idempotency, error handling): https://docs.groundtech.co/docs/portfolio-wallets/api-conventions - The wallet lifecycle (create, deposit, earn, withdraw): https://docs.groundtech.co/docs/portfolio-wallets/introduction - Wallet creation guide: https://docs.groundtech.co/docs/portfolio-wallets/create-wallet - Deposits lifecycle: https://docs.groundtech.co/docs/portfolio-wallets/deposits - Yield sources and strategy construction: https://docs.groundtech.co/docs/portfolio-wallets/yield-sources - Balances and yield tracking: https://docs.groundtech.co/docs/portfolio-wallets/balances-and-yield - Withdrawal flow: https://docs.groundtech.co/docs/portfolio-wallets/withdraw-funds - The withdrawal approval flow (Turnkey signing): https://docs.groundtech.co/docs/portfolio-wallets/transaction-approvals - Webhook events and signature verification: https://docs.groundtech.co/docs/portfolio-wallets/webhooks https://docs.groundtech.co/docs/portfolio-wallets/webhook-signature-verification https://docs.groundtech.co/docs/portfolio-wallets/webhook-payload-examples - Supported chains: https://docs.groundtech.co/docs/portfolio-wallets/supported-chains 3. Then present a written integration plan that covers: - Which parts of our codebase you'll modify or create - How you'll map Ground wallets to our user model (1:1 per user? pooled?) - Which yield strategy you recommend and why, given our liquidity needs - How you'll handle webhook ingestion and signature verification - How you'll surface balances and yield to our users - How you'll handle the withdrawal -> Turnkey approval -> completion flow - What new database tables/columns are needed - What new environment variables are needed Do NOT write any code yet. Wait for my approval of the plan before proceeding. ``` ```text Step 2: Implementation theme={"theme":{"light":"github-light","dark":"github-dark"}} Proceed with the integration plan. Implement the following in order: 1. Environment setup - Add GROUND_API_TOKEN and GROUND_WEBHOOK_SIGNING_SECRET to our secrets/env config - Use sandbox base URL: https://sandbox.groundtech.co - See API conventions for auth details: https://docs.groundtech.co/docs/portfolio-wallets/api-conventions 2. Ground API client - Create a thin HTTP client for Ground's API with: - Bearer token auth - Idempotent request IDs (UUID v4) on all POST requests - Retry with backoff on 429 and 5xx - Structured error handling using Ground's {error, code} response format - Reference: https://docs.groundtech.co/docs/portfolio-wallets/api-conventions 3. Wallet creation flow - When a user action triggers wallet creation, call POST /v2/wallets with the chosen strategy API ref: https://docs.groundtech.co/api-reference/create-wallet Guide: https://docs.groundtech.co/docs/portfolio-wallets/create-wallet - Store the wallet ID and deposit addresses in our database - Build a strategy manually from the yield source catalog, prioritizing liquidity where needed (for example, overweighting faster-withdrawal sources for user balances that need quick access) Guide: https://docs.groundtech.co/docs/portfolio-wallets/yield-sources 4. Deposit tracking - After wallet creation, provide the user with deposit addresses - Register a webhook for portfolio_wallet.deposit.status_changed Webhook setup: https://docs.groundtech.co/docs/portfolio-wallets/webhooks API ref: https://docs.groundtech.co/api-reference/create-webhook - When deposits are confirmed, update the user's displayed balance Guide: https://docs.groundtech.co/docs/portfolio-wallets/deposits 5. Balance and yield display - Register webhooks for portfolio_wallet.deposit.status_changed, portfolio_wallet.rebalance.status_changed, and portfolio_wallet.withdrawal.status_changed - On each lifecycle event, fetch GET /v2/wallets/:id and sync totalUsd, withdrawableUsd, and earnedUsd to our database. API ref: https://docs.groundtech.co/api-reference/get-wallet Guide: https://docs.groundtech.co/docs/portfolio-wallets/balances-and-yield - Expose these through our existing user-facing balance endpoints/UI 6. Withdrawal flow - Expose a withdrawal action that calls POST /v2/wallets/:id/withdrawal-preview first, then POST /v2/wallets/:id/withdrawals Preview API ref: https://docs.groundtech.co/api-reference/withdrawal-preview Withdraw API ref: https://docs.groundtech.co/api-reference/withdraw Guide: https://docs.groundtech.co/docs/portfolio-wallets/withdraw-funds - Register a webhook for portfolio_wallet.withdrawal.status_changed - Handle the pending_customer_approval status by routing the Turnkey activity to our signing flow Guide: https://docs.groundtech.co/docs/portfolio-wallets/transaction-approvals - Update withdrawal status in our system as it progresses 7. Webhook handler - Create a POST endpoint to receive Ground webhooks - Verify the Ground-Signature header using HMAC-SHA256 (see Ground's docs for the exact scheme: t=,v1= over timestamp.rawBody) Signature verification: https://docs.groundtech.co/docs/portfolio-wallets/webhook-signature-verification Payload examples: https://docs.groundtech.co/docs/portfolio-wallets/webhook-payload-examples - Route events to the appropriate handler by event type - Respond with 200 quickly; process asynchronously After implementation, list any manual steps I need to take (e.g. running migrations, setting env vars, registering the webhook URL with Ground). ``` *** ## Cross-Border Payments / Stablecoin Money Movement Use this if you are building a cross-border payments, remittance, or stablecoin money movement product (similar to Bridge, OpenFX, etc.) where funds transit through your platform and you want to earn yield on float/held balances. ```text Step 1: Discovery & Planning theme={"theme":{"light":"github-light","dark":"github-dark"}} You are integrating Ground's Portfolio Wallets API into our product. Ground is a yield infrastructure provider -- their Portfolio Wallets API lets us allocate stablecoin balances across multiple yield sources via a single REST API. Ground handles allocation, rebalancing, withdrawals, and reporting. We are a cross-border payments / stablecoin money movement platform. Our goal is to earn yield on float -- the stablecoins that sit in our system between when we receive funds and when we pay them out. Our priorities are: - Instant or near-instant liquidity (we need to pay out on short notice) - Multi-chain support (we operate across multiple EVM chains) - Automated treasury management (minimal manual intervention) - Yield is a secondary revenue stream, not our core product Before writing any code, do the following: 1. Read our existing codebase to understand: - What language/framework we use - How we currently hold and move stablecoins - Our payment/transfer lifecycle (receive -> hold -> payout) - What chains we currently operate on - How we manage treasury wallets today - How long funds typically sit idle (minutes? hours? days?) - Whether we have an existing webhook ingestion system - How we store secrets and handle environment configuration 2. Read Ground's API documentation using the specific links below: - API conventions (auth, pagination, idempotency, error handling): https://docs.groundtech.co/docs/portfolio-wallets/api-conventions - The wallet lifecycle (create, deposit, earn, withdraw): https://docs.groundtech.co/docs/portfolio-wallets/introduction - Wallet creation guide: https://docs.groundtech.co/docs/portfolio-wallets/create-wallet - Deposits lifecycle: https://docs.groundtech.co/docs/portfolio-wallets/deposits - Yield sources -- especially which have the fastest estimated withdrawals: https://docs.groundtech.co/docs/portfolio-wallets/yield-sources - Withdrawal preview and the withdrawal lifecycle: https://docs.groundtech.co/docs/portfolio-wallets/withdraw-funds - The Turnkey transaction approval flow: https://docs.groundtech.co/docs/portfolio-wallets/transaction-approvals - Webhook events and signature verification: https://docs.groundtech.co/docs/portfolio-wallets/webhooks https://docs.groundtech.co/docs/portfolio-wallets/webhook-signature-verification https://docs.groundtech.co/docs/portfolio-wallets/webhook-payload-examples - Supported chains and cross-chain bridging: https://docs.groundtech.co/docs/portfolio-wallets/supported-chains - Polling (alternative to webhooks for status tracking): https://docs.groundtech.co/docs/portfolio-wallets/polling - Balances and yield tracking: https://docs.groundtech.co/docs/portfolio-wallets/balances-and-yield 3. Then present a written integration plan that covers: - How you'll architect the Ground wallet(s) relative to our payment flows (e.g. one treasury wallet vs. per-corridor wallets) - Which yield strategy you recommend -- given our need for instant liquidity, you should heavily weight or exclusively use instant-liquidity sources - How you'll sweep idle funds into the Ground wallet - How you'll trigger withdrawals when we need to pay out - The timing budget: how withdrawal timing (unwind + bridge) fits within our payout SLA - How you'll handle the Turnkey approval step in the withdrawal flow - How you'll use webhooks vs. polling for withdrawal status tracking - What changes to our database schema are needed - What new environment variables are needed Do NOT write any code yet. Wait for my approval of the plan before proceeding. ``` ```text Step 2: Implementation theme={"theme":{"light":"github-light","dark":"github-dark"}} Proceed with the integration plan. Implement the following in order: 1. Environment setup - Add GROUND_API_TOKEN and GROUND_WEBHOOK_SIGNING_SECRET to our secrets/env config - Use sandbox base URL: https://sandbox.groundtech.co - See API conventions for auth details: https://docs.groundtech.co/docs/portfolio-wallets/api-conventions 2. Ground API client - Create a thin HTTP client for Ground's API with: - Bearer token auth - Idempotent request IDs (UUID v4) on all POST requests - Retry with backoff on 429 and 5xx - Structured error handling using Ground's {error, code} response format - Reference: https://docs.groundtech.co/docs/portfolio-wallets/api-conventions 3. Treasury wallet setup - Create Ground wallet(s) with a strategy optimized for instant liquidity API ref: https://docs.groundtech.co/api-reference/create-wallet Guide: https://docs.groundtech.co/docs/portfolio-wallets/create-wallet - Select wallet allocations directly from the yield source catalog. For payout-sensitive flows, prefer sources with the fastest estimated withdrawals and keep the strategy simple enough to meet your payout SLA. Guide: https://docs.groundtech.co/docs/portfolio-wallets/yield-sources - Store wallet ID(s) and deposit addresses in our database 4. Sweep-in flow - Identify the point in our payment lifecycle where funds become idle - Implement a sweep that sends idle stablecoins to the Ground wallet's deposit address on the appropriate chain - Track sweep deposits via the portfolio_wallet.deposit.status_changed webhook Webhook setup: https://docs.groundtech.co/docs/portfolio-wallets/webhooks API ref: https://docs.groundtech.co/api-reference/create-webhook Guide: https://docs.groundtech.co/docs/portfolio-wallets/deposits 5. Withdrawal / payout-out flow - When we need to pay out, call POST /v2/wallets/:id/withdrawal-preview to confirm available balance and timing Preview API ref: https://docs.groundtech.co/api-reference/withdrawal-preview - Initiate withdrawal with POST /v2/wallets/:id/withdrawals to the destination chain and address Withdraw API ref: https://docs.groundtech.co/api-reference/withdraw Guide: https://docs.groundtech.co/docs/portfolio-wallets/withdraw-funds - Handle the Turnkey approval step (pending_customer_approval payout status) Guide: https://docs.groundtech.co/docs/portfolio-wallets/transaction-approvals - Track withdrawal completion via webhook or polling Polling guide: https://docs.groundtech.co/docs/portfolio-wallets/polling 6. Balance monitoring - Register webhooks for portfolio_wallet.deposit.status_changed, portfolio_wallet.rebalance.status_changed, and portfolio_wallet.withdrawal.status_changed - Sync wallet balances to our system for treasury dashboarding after each lifecycle event API ref: https://docs.groundtech.co/api-reference/get-wallet Guide: https://docs.groundtech.co/docs/portfolio-wallets/balances-and-yield - Track earned yield separately for revenue reporting 7. Webhook handler - Create a POST endpoint to receive Ground webhooks - Verify the Ground-Signature header using HMAC-SHA256 Signature verification: https://docs.groundtech.co/docs/portfolio-wallets/webhook-signature-verification Payload examples: https://docs.groundtech.co/docs/portfolio-wallets/webhook-payload-examples - Route events by type; respond 200 immediately and process async After implementation, list any manual steps I need to take (e.g. running migrations, setting env vars, registering the webhook URL with Ground). ``` *** ## Non-Custodial Wallet Provider Use this if you are building a self-custody wallet, smart wallet, or MPC wallet product where users hold their own keys and you want to offer yield features without taking custody of funds. ```text Step 1: Discovery & Planning theme={"theme":{"light":"github-light","dark":"github-dark"}} You are integrating Ground's Portfolio Wallets API into our product. Ground is a yield infrastructure provider -- their Portfolio Wallets API lets us allocate stablecoin deposits across multiple yield sources via a single REST API. Ground handles allocation, rebalancing, withdrawals, and reporting. Ground wallets use Turnkey for non-custodial key management -- private keys are never held by Ground. We are a non-custodial wallet provider. Our goal is to offer yield-earning features to our users while preserving our non-custodial architecture. Our priorities are: - Users remain in control of their funds (non-custodial UX) - The Turnkey approval flow is critical -- users must approve withdrawals - Clear separation between user funds (each user gets their own Ground wallet) - Transparency: users should see exactly where their funds are allocated and what yield they are earning Before writing any code, do the following: 1. Read our existing codebase to understand: - What language/framework we use for our backend and client apps - How users currently manage their wallet(s) in our product - Whether we already integrate with Turnkey or a similar key management system - How we handle transaction signing and approval UX today - How we display balances and transaction history to users - Whether we have an existing webhook ingestion system - How we store secrets and handle environment configuration 2. Read Ground's API documentation using the specific links below: - API conventions (auth, pagination, idempotency, error handling): https://docs.groundtech.co/docs/portfolio-wallets/api-conventions - The wallet lifecycle (create, deposit, earn, withdraw): https://docs.groundtech.co/docs/portfolio-wallets/introduction - Wallet creation guide: https://docs.groundtech.co/docs/portfolio-wallets/create-wallet - Deposits lifecycle: https://docs.groundtech.co/docs/portfolio-wallets/deposits - The transaction approval flow -- specifically how Turnkey activity IDs surface on withdrawal payout legs (pending_customer_approval status): https://docs.groundtech.co/docs/portfolio-wallets/transaction-approvals - Yield sources and strategy construction: https://docs.groundtech.co/docs/portfolio-wallets/yield-sources - Balances and yield tracking: https://docs.groundtech.co/docs/portfolio-wallets/balances-and-yield - Withdrawal flow: https://docs.groundtech.co/docs/portfolio-wallets/withdraw-funds - How deposit addresses work (per-chain addresses per wallet): https://docs.groundtech.co/docs/portfolio-wallets/supported-chains - Webhook events and signature verification: https://docs.groundtech.co/docs/portfolio-wallets/webhooks https://docs.groundtech.co/docs/portfolio-wallets/webhook-signature-verification https://docs.groundtech.co/docs/portfolio-wallets/webhook-payload-examples 3. Then present a written integration plan that covers: - How you'll create and manage Ground wallets per user (1:1 mapping) - How the yield opt-in flow works from the user's perspective - Which yield strategies to offer and whether to let users choose - How users will fund their Ground wallet from their existing wallet - How you'll surface positions, balances, and earned yield in the UI - How you'll integrate the Turnkey approval into our existing signing UX -- this is the most important part for our architecture - How you'll handle the full withdrawal lifecycle from user request through Turnkey approval to fund delivery - What new backend endpoints, database tables, and client UI are needed - What new environment variables are needed Do NOT write any code yet. Wait for my approval of the plan before proceeding. ``` ```text Step 2: Implementation theme={"theme":{"light":"github-light","dark":"github-dark"}} Proceed with the integration plan. Implement the following in order: 1. Environment setup - Add GROUND_API_TOKEN and GROUND_WEBHOOK_SIGNING_SECRET to our secrets/env config - Use sandbox base URL: https://sandbox.groundtech.co - See API conventions for auth details: https://docs.groundtech.co/docs/portfolio-wallets/api-conventions 2. Ground API client - Create a thin HTTP client for Ground's API with: - Bearer token auth - Idempotent request IDs (UUID v4) on all POST requests - Retry with backoff on 429 and 5xx - Structured error handling using Ground's {error, code} response format - Reference: https://docs.groundtech.co/docs/portfolio-wallets/api-conventions 3. Yield opt-in and wallet creation - Create a user-facing flow where a user opts in to earning yield - On opt-in, call POST /v2/wallets to create a dedicated Ground wallet for that user API ref: https://docs.groundtech.co/api-reference/create-wallet Guide: https://docs.groundtech.co/docs/portfolio-wallets/create-wallet - Let the user choose a strategy (or recommend a default) from the yield source catalog, and explain the tradeoffs based on source APY and estimated withdrawal time Guide: https://docs.groundtech.co/docs/portfolio-wallets/yield-sources - Store the Ground wallet ID mapped to the user in our database - Display the wallet's per-chain deposit addresses to the user 4. Deposit flow - Guide the user to send USDC from their existing wallet to the Ground wallet deposit address - Register a webhook for portfolio_wallet.deposit.status_changed Webhook setup: https://docs.groundtech.co/docs/portfolio-wallets/webhooks API ref: https://docs.groundtech.co/api-reference/create-webhook - Show deposit status progression (processing -> completed, or failed) in the user's transaction history Guide: https://docs.groundtech.co/docs/portfolio-wallets/deposits 5. Portfolio display - Register webhooks for portfolio_wallet.deposit.status_changed, portfolio_wallet.rebalance.status_changed, and portfolio_wallet.withdrawal.status_changed - Display to the user: - Total balance (totalUsd) - Yield earned (earnedUsd from balance, or use GET /v2/wallets/:id for detailed breakdown) API ref: https://docs.groundtech.co/api-reference/get-wallet Guide: https://docs.groundtech.co/docs/portfolio-wallets/balances-and-yield - Position breakdown (which yield sources, allocation percentages, per- position value) - Withdrawable balance (withdrawableUsd) 6. Withdrawal flow with Turnkey approval - User initiates a withdrawal from the UI - Call POST /v2/wallets/:id/withdrawal-preview to show the user what's available and estimated timing Preview API ref: https://docs.groundtech.co/api-reference/withdrawal-preview - On user confirmation, call POST /v2/wallets/:id/withdrawals Withdraw API ref: https://docs.groundtech.co/api-reference/withdraw Guide: https://docs.groundtech.co/docs/portfolio-wallets/withdraw-funds - Register a webhook for portfolio_wallet.withdrawal.status_changed - When a payout leg or external payout step reaches pending_customer_approval status: - Open the pending approval in Ground Portal or your enabled approval integration and match the activity by withdrawal/leg - Route this to our existing transaction signing / approval UX - The user approves the Turnkey activity through our signing flow Guide: https://docs.groundtech.co/docs/portfolio-wallets/transaction-approvals - Track the withdrawal through to completion and update the UI 7. Webhook handler - Create a POST endpoint to receive Ground webhooks - Verify the Ground-Signature header using HMAC-SHA256 Signature verification: https://docs.groundtech.co/docs/portfolio-wallets/webhook-signature-verification Payload examples: https://docs.groundtech.co/docs/portfolio-wallets/webhook-payload-examples - Route events by type; respond 200 immediately and process async - Update user-facing state on each event so the UI reflects real-time status After implementation, list any manual steps I need to take (e.g. running migrations, setting env vars, registering the webhook URL with Ground). ``` *** ## Tips for best results * **Run Step 1 first, review the plan, then run Step 2.** The two-step approach prevents the agent from making wrong assumptions about your codebase. * **Answer the agent's questions.** During Step 1, the agent will likely ask clarifying questions about your architecture. Answer them -- this is by design and prevents hallucinated code. * **Use sandbox first.** All prompts target `https://sandbox.groundtech.co`. Test with Sepolia USDC or Mock Sepolia USDT. * **Check the webhook handler carefully.** Signature verification is security-critical. Review the generated `Ground-Signature` verification code against [our reference implementation](/docs/portfolio-wallets/webhook-signature-verification). * **The Turnkey approval flow is product-specific.** The prompts intentionally leave room for the agent to ask how your signing infrastructure works rather than assuming a specific Turnkey integration pattern.