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:- A Ground sandbox API token (contact your Ground rep if you don’t have one)
- Your AI coding agent has access to your project’s codebase
- Access to Ground’s API documentation
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.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.
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=<timestamp>,v1=<hmac> 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.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.
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.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.
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-Signatureverification code against our reference implementation. - 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.