# Ground

> Ground developer documentation for Portfolio Wallets and webhooks.

## Docs

- [Create risk rule](https://docs.groundtech.co/api-reference-v2/create-risk-rule.md): Creates a risk rule for one yield source within one portfolio wallet.
- [Create a portfolio wallet](https://docs.groundtech.co/api-reference-v2/create-wallet.md): Creates a new wallet with the given strategy allocation. 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: creating` while they provision.
- [Create a webhook](https://docs.groundtech.co/api-reference-v2/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 a webhook](https://docs.groundtech.co/api-reference-v2/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-v2/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-v2/get-deposit.md): Returns a single deposit by its ID.
- [Get a portfolio wallet](https://docs.groundtech.co/api-reference-v2/get-wallet.md): Returns the wallet with balances, strategy, positions, and deposit addresses.
- [Get wallets overview](https://docs.groundtech.co/api-reference-v2/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-v2/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-v2/get-withdrawal.md): Returns a single withdrawal by its ID.
- [List accounting activity](https://docs.groundtech.co/api-reference-v2/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 deposits](https://docs.groundtech.co/api-reference-v2/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 risk actions](https://docs.groundtech.co/api-reference-v2/list-risk-actions.md): Returns risk-triggered actions, including pending approvals and executed rebalances, across one or more portfolio wallets.
- [List risk alerts](https://docs.groundtech.co/api-reference-v2/list-risk-alerts.md): Returns triggered or resolved risk alerts across one or more portfolio wallets.
- [List risk metrics](https://docs.groundtech.co/api-reference-v2/list-risk-metrics.md): Returns normalized risk metric observations for yield sources referenced by the authenticated organization's portfolio wallets. Use `portfolioWalletIds` to query across a dashboard-sized set of wallets in one request.
- [List risk rules](https://docs.groundtech.co/api-reference-v2/list-risk-rules.md): Returns yield-source-scoped risk rules for the authenticated organization.
- [List yield sources](https://docs.groundtech.co/api-reference-v2/list-strategies.md): Returns the active yield source catalog available for wallet strategies. The catalog is environment-specific.
- [List portfolio wallets](https://docs.groundtech.co/api-reference-v2/list-wallets.md): Returns a cursor-paginated list of wallets for the authenticated organization.
- [List webhook events](https://docs.groundtech.co/api-reference-v2/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-v2/list-webhook-events-by-webhook.md): Returns a cursor-paginated delivery event feed for one webhook.
- [List webhooks](https://docs.groundtech.co/api-reference-v2/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-v2/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-v2/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-v2/optimize-strategy.md): Returns a yield-maximizing allocation that satisfies the supplied constraints. All request fields are optional; an empty body returns 100% to the highest-APY active source. The `allocations` array in the response has the same shape as the `strategy.allocations` input on `POST /v2/wallets`, so caller…
- [Ping](https://docs.groundtech.co/api-reference-v2/ping.md): Checks the system status and returns a simple response to confirm the API is reachable.
- [Resolve risk action](https://docs.groundtech.co/api-reference-v2/resolve-risk-action.md): Approves or rejects a pending risk action. Approving a `request_rebalance_out` action commits a risk-rule-triggered rebalance when a valid plan exists. `auto_rebalance_out` actions are executed by the risk engine without customer approval.
- [Update risk rule](https://docs.groundtech.co/api-reference-v2/update-risk-rule.md): Updates an existing yield-source-scoped risk rule. Send only fields to change.
- [Update wallet strategy](https://docs.groundtech.co/api-reference-v2/update-strategy.md): Replaces the wallet's strategy allocation. Idempotent on `requestId` — if a strategy update with the same `requestId` and identical allocations already exists, the current wallet is returned. If `requestId` was used with different allocations, a `409 request_id_conflict` is returned.
- [Update a portfolio wallet](https://docs.groundtech.co/api-reference-v2/update-wallet.md): Updates wallet metadata. Currently supports changing the wallet `label`.
- [Withdraw funds](https://docs.groundtech.co/api-reference-v2/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. Token defaults to USDC.
- [Preview a withdrawal](https://docs.groundtech.co/api-reference-v2/withdrawal-preview.md): Returns the withdrawable balance for a given destination chain and, optionally, validates that a specific withdrawal amount is feasible. Token defaults to USDC.
- [Get wallet yield](https://docs.groundtech.co/api-reference/portfolio-wallets/get-wallet-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.
- [List activity](https://docs.groundtech.co/api-reference/portfolio-wallets/list-activity.md): Returns customer-facing wallet activity across the authenticated organization. Pass one or more `walletId` query parameters to filter to specific wallets.
- [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.
- [Alerts and Recovery](https://docs.groundtech.co/docs/portfolio-wallets/risk/alerts-and-recovery.md): The risk alert lifecycle: how breaches open alerts, how recovery resolves them automatically, and how to query them.
- [Creating Risk Rules](https://docs.groundtech.co/docs/portfolio-wallets/risk/creating-rules.md): Define risk rules on a yield source: metric, threshold or velocity, and the outcome that fires when the rule breaches.
- [Outcomes and Actions](https://docs.groundtech.co/docs/portfolio-wallets/risk/outcomes-and-actions.md): What happens when a risk rule fires (alert, block allocation, or exit), and how to approve the actions it creates.
- [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 Turnkey transaction approvals work, how to approve them, and how 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 yield sources, rate semantics, and liquidity expectations.

## OpenAPI Specs

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