# Ground

> Ground developer documentation for Portfolio Wallets and webhooks.

## Docs

- [Compute yield](https://docs.groundtech.co/api-reference/compute-yield.md): Returns cumulative yield data and supporting metrics for a wallet. Use this to display "You've earned $X" and yield source APY breakdowns.
- [Create address book entry](https://docs.groundtech.co/api-reference/create-address-book-entry.md): Adds a withdrawal destination to the organization's address book. Requires an organization owner or admin.
- [Create Turnkey activity approval request](https://docs.groundtech.co/api-reference/create-turnkey-activity-approval-request.md): Returns the Turnkey approve or reject request payload that the customer signer must stamp locally before submitting it to the vote endpoint. Ground validates the activity, sub-organization, fingerprint, and actionable state before returning the request.
- [Create a portfolio wallet](https://docs.groundtech.co/api-reference/create-wallet.md): Creates a new wallet with token-keyed strategy allocations. Each included stablecoin group must sum to 100 percent. Idempotent on `requestId` — if a wallet with the same `requestId` already exists, the existing wallet is returned. Always returns `200`; newly created wallets are returned with `status…
- [Create a webhook](https://docs.groundtech.co/api-reference/create-webhook.md): Registers a webhook for the authenticated organization. The signing secret is returned only in the creation response. Only `portfolio_wallet.*` event types are accepted.
- [Delete address book entry](https://docs.groundtech.co/api-reference/delete-address-book-entry.md): Permanently removes an address book entry. Deleting the last entry turns withdrawal address enforcement off for the organization.
- [Delete a webhook](https://docs.groundtech.co/api-reference/delete-webhook.md): Deletes a webhook registration by its ID. No further events are delivered to its URL once it is deleted.
- [Get accounting yield period summary](https://docs.groundtech.co/api-reference/get-accounting-yield-period-summary.md): Returns an accounting performance summary for a period, scoped to either one wallet or the authenticated organization. Period performance metrics can be negative and are distinct from customer-facing displayed yield.
- [Get a deposit](https://docs.groundtech.co/api-reference/get-deposit.md): Returns a single deposit by its ID.
- [Get a portfolio wallet](https://docs.groundtech.co/api-reference/get-wallet.md): Returns the wallet with balances, strategy, positions, and deposit addresses.
- [Get wallets overview](https://docs.groundtech.co/api-reference/get-wallets-overview.md): Returns aggregate balance and yield totals across the authenticated organization's wallets.
- [Get a webhook](https://docs.groundtech.co/api-reference/get-webhook.md): Returns a single webhook registration by its ID. The signing `secret` is never included; it is only returned once, in the create response.
- [Get a withdrawal](https://docs.groundtech.co/api-reference/get-withdrawal.md): Returns a single withdrawal by its ID.
- [List accounting activity](https://docs.groundtech.co/api-reference/list-accounting-activity.md): Returns customer-facing accounting journal lines for either one wallet or the authenticated organization. Rows with the same journalEntryId belong to the same journal entry. nativeUnits and amountUsd are signed: positive values increase that account bucket and negative values decrease it.
- [List activity](https://docs.groundtech.co/api-reference/list-activity.md): Returns customer-facing wallet activity across the authenticated organization. Pass one or more `walletId` query parameters to filter to specific wallets.
- [List address book entries](https://docs.groundtech.co/api-reference/list-address-book-entries.md): Returns the organization's withdrawal address book entries. A non-empty address book means withdrawals are restricted to listed destinations.
- [List deposits](https://docs.groundtech.co/api-reference/list-deposits.md): Returns a cursor-paginated list of deposits for a specific wallet. Likely inbound USDC transfers to workflow-idle wallets can appear as `processing` before finality; these rows are not credited to balances until posting completes.
- [List pending Turnkey approval activities](https://docs.groundtech.co/api-reference/list-pending-turnkey-activities.md): Returns pending customer-approval activities for the authenticated organization, joined with Ground wallet and withdrawal context. Activities already voted on by the requester may be omitted.
- [List yield sources](https://docs.groundtech.co/api-reference/list-strategies.md): Returns the environment-specific yield source catalog for wallet strategies. Sources in `emergency_freeze` remain visible with that mode so clients can show their maintenance status, but they must not be selected for new allocations. Use `depositToken` to place each source in the matching USDC or US…
- [List portfolio wallets](https://docs.groundtech.co/api-reference/list-wallets.md): Returns a cursor-paginated list of wallets for the authenticated organization.
- [List webhook events](https://docs.groundtech.co/api-reference/list-webhook-events.md): Returns a cursor-paginated delivery event feed across all active webhooks for the organization.
- [List events for a webhook](https://docs.groundtech.co/api-reference/list-webhook-events-by-webhook.md): Returns a cursor-paginated delivery event feed for one webhook.
- [List webhooks](https://docs.groundtech.co/api-reference/list-webhooks.md): Returns a cursor-paginated list of active webhook registrations for the authenticated organization. The signing `secret` is never included in list responses — it is only returned once, in the create response.
- [List withdrawals](https://docs.groundtech.co/api-reference/list-withdrawals.md): Returns a cursor-paginated list of withdrawals for a specific wallet.
- [Lookup a wallet deposit by tx hash](https://docs.groundtech.co/api-reference/lookup-deposit.md): Fetch a single deposit by its onchain transaction hash. `chain` is optional; if provided, it must match the deposit's recorded chain.
- [Optimize wallet strategy](https://docs.groundtech.co/api-reference/optimize-strategy.md): Returns a yield-maximizing allocation that satisfies the supplied constraints. The optimizer considers only sources whose `depositToken` matches the requested `token`. All request fields are optional; `token` defaults to `usdc`, so an empty body returns 100% to the highest-APY active USDC source. Th…
- [Ping](https://docs.groundtech.co/api-reference/ping.md): Checks the system status and returns a simple response to confirm the API is reachable.
- [Update wallet strategy](https://docs.groundtech.co/api-reference/update-strategy.md): Replaces the included token strategy groups and preserves omitted groups. Idempotent on `requestId` — if a strategy update with the same `requestId` and identical allocations already exists, the canonical strategy allocations are returned. If `requestId` was used with different allocations, a `409 r…
- [Update a portfolio wallet](https://docs.groundtech.co/api-reference/update-wallet.md): Updates wallet metadata. Currently supports changing the wallet `label`.
- [Vote on Turnkey activity](https://docs.groundtech.co/api-reference/vote-turnkey-activity.md): Submits a customer-generated Turnkey approval stamp for a pending activity. The customer signs the Turnkey request locally; Ground receives only the stamp and validates the request action, sub-organization, fingerprint, and activity state before forwarding it to Turnkey.
- [Withdraw funds](https://docs.groundtech.co/api-reference/withdraw.md): Initiates a withdrawal from the wallet. Idempotent on `requestId` — if a withdrawal with the same `requestId` already exists, the existing withdrawal is returned. The token is required. USDC supports the documented CCTP chain set; USDT supports Ethereum only in production and Ethereum Sepolia in san…
- [Preview a withdrawal](https://docs.groundtech.co/api-reference/withdrawal-preview.md): Returns the withdrawable balance for a given destination chain and, optionally, validates that a specific withdrawal amount is feasible. The token is required. USDC supports the documented CCTP chain set; USDT supports Ethereum only in production and Ethereum Sepolia in sandbox.
- [API Changelog](https://docs.groundtech.co/docs/changelog.md): Breaking changes and notable updates to the Ground API.
- [Address Book](https://docs.groundtech.co/docs/portfolio-wallets/address-book.md): Manage the organization withdrawal address whitelist via the API.
- [Agentic Installation](https://docs.groundtech.co/docs/portfolio-wallets/agentic-installation.md): Copy-paste prompts that guide an AI coding agent through a complete Ground Portfolio Wallets integration, tailored to your product type.
- [API Conventions](https://docs.groundtech.co/docs/portfolio-wallets/api-conventions.md): Authentication, environments, pagination, idempotency, rate limiting, and error handling.
- [Balances and Yield](https://docs.groundtech.co/docs/portfolio-wallets/balances-and-yield.md): Monitor wallet balances, positions, and yield metrics.
- [Calculating Yield Accrual](https://docs.groundtech.co/docs/portfolio-wallets/calculating-yield-accrual.md): Understand how yield accrues across different position types and how to display earnings to your users.
- [Create a Wallet](https://docs.groundtech.co/docs/portfolio-wallets/create-wallet.md): Create a portfolio wallet and poll for activation.
- [Deposits](https://docs.groundtech.co/docs/portfolio-wallets/deposits.md): Fund a portfolio wallet and track deposit lifecycle.
- [Onchain Architecture](https://docs.groundtech.co/docs/portfolio-wallets/flow-of-funds.md): How deposits and withdrawals move through Ground's on-chain contract stack.
- [Portfolio Wallets Overview](https://docs.groundtech.co/docs/portfolio-wallets/introduction.md): Multi-strategy yield wallets with blended rates, automated rebalancing, and liquidity profiles.
- [Optimize Strategy](https://docs.groundtech.co/docs/portfolio-wallets/optimize-strategy.md): Given customer preferences, returns a yield-maximizing allocation that plugs directly into wallet creation.
- [Polling](https://docs.groundtech.co/docs/portfolio-wallets/polling.md): Examples for scheduled monitoring with list and get endpoints.
- [Quickstart](https://docs.groundtech.co/docs/portfolio-wallets/quickstart.md): Create a wallet, deposit funds, and withdraw — all in 5 minutes.
- [Supported Chains](https://docs.groundtech.co/docs/portfolio-wallets/supported-chains.md): Portfolio wallet deposit and withdrawal coverage.
- [Transaction Approvals](https://docs.groundtech.co/docs/portfolio-wallets/transaction-approvals.md): How customer approvals work, when they are required, and what to verify before signing.
- [Update Strategy](https://docs.groundtech.co/docs/portfolio-wallets/update-strategy.md): Change a wallet's yield allocation after creation.
- [Update a Wallet](https://docs.groundtech.co/docs/portfolio-wallets/update-wallet.md): Rename a portfolio wallet.
- [Webhook payload examples](https://docs.groundtech.co/docs/portfolio-wallets/webhook-payload-examples.md): Example JSON bodies for Portfolio Wallet webhook events.
- [Webhook signature verification](https://docs.groundtech.co/docs/portfolio-wallets/webhook-signature-verification.md): Verify Ground webhook request authenticity using Stripe-style HMAC.
- [Webhooks](https://docs.groundtech.co/docs/portfolio-wallets/webhooks.md): Register webhooks and receive real-time Portfolio Wallet events.
- [Withdraw Funds](https://docs.groundtech.co/docs/portfolio-wallets/withdraw-funds.md): Preview, initiate, and track portfolio wallet withdrawals.
- [Yield Sources](https://docs.groundtech.co/docs/portfolio-wallets/yield-sources.md): Available RWA and DeFi yield sources, rate semantics, and liquidity expectations.
- [Contract Addresses](https://docs.groundtech.co/docs/resources/addresses.md): Current production and sandbox contract and program deployments.
- [Security](https://docs.groundtech.co/docs/security/custody-model.md): Security reviews, custody model, wallet controls, and deployment references.

## OpenAPI Specs

- [swagger-combined](https://docs.groundtech.co/swagger/swagger-combined.yaml)