# Ground

> Ground developer documentation for Portfolio Wallets, gtokens, MicroVaults, and webhooks.

- [Introduction](https://docs.groundtech.co/docs/introduction.md)
- [Agentic Installation](https://docs.groundtech.co/docs/agentic-installation.md): Choose a Ground integration by balance ownership and signer, then validate a complete sandbox round trip with your coding agent.
- [Portfolio Wallets Overview](https://docs.groundtech.co/docs/portfolio-wallets/introduction.md): Multi-strategy yield wallets with blended rates, automated rebalancing, and liquidity profiles.
- [Quickstart](https://docs.groundtech.co/docs/portfolio-wallets/quickstart.md): Create a sandbox wallet, fund it, and track a withdrawal through settlement.
- [Example: Treasury Portfolio](https://docs.groundtech.co/docs/portfolio-wallets/integration-guides/treasury-portfolio-wallet.md)
- [Example: Neobank/Exchanges](https://docs.groundtech.co/docs/portfolio-wallets/integration-guides/neobank-customer-portfolio-wallet.md)
- [Power Yield for Stellar Balances](https://docs.groundtech.co/docs/portfolio-wallets/integration-guides/stellar.md): Use Ground to offer yield on customer USDC held on Stellar. Ground provides the wallet, allocation, bridging, and settlement infrastructure while your application owns the customer experience.
- [Yield Sources](https://docs.groundtech.co/docs/portfolio-wallets/yield-sources.md): Available RWA and DeFi yield sources, rate semantics, and liquidity expectations.
- [Supported Chains](https://docs.groundtech.co/docs/portfolio-wallets/supported-chains.md): Portfolio wallet network coverage, address formats, and sandbox assets.
- [API Conventions](https://docs.groundtech.co/docs/portfolio-wallets/api-conventions.md): Authentication, environments, pagination, idempotency, rate limiting, and error handling.
- [Onchain Architecture](https://docs.groundtech.co/docs/portfolio-wallets/flow-of-funds.md): How deposits, direct protocol positions, and Ground RWA Vault positions move through Ground's onchain contracts and programs.
- [Create a Wallet](https://docs.groundtech.co/docs/portfolio-wallets/create-wallet.md): Create a portfolio wallet and poll for activation.
- [Update a Wallet](https://docs.groundtech.co/docs/portfolio-wallets/update-wallet.md): Rename a portfolio wallet.
- [Deposits](https://docs.groundtech.co/docs/portfolio-wallets/deposits.md): Fund a portfolio wallet and track deposit lifecycle.
- [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.
- [Update Strategy](https://docs.groundtech.co/docs/portfolio-wallets/update-strategy.md): Change a wallet's yield allocation after creation.
- [How Auto Rebalancing Works](https://docs.groundtech.co/docs/portfolio-wallets/auto-rebalancing.md): Choose automatic or manual allocation and understand when Ground moves funds toward your portfolio targets.
- [Withdraw Funds](https://docs.groundtech.co/docs/portfolio-wallets/withdraw-funds.md): Preview, initiate, and track portfolio wallet withdrawals.
- [Address Book](https://docs.groundtech.co/docs/portfolio-wallets/address-book.md): Manage the organization withdrawal address whitelist via the API.
- [Fee Wrappers (Beta)](https://docs.groundtech.co/docs/portfolio-wallets/fee-wrappers.md): Collect fees while your end users' funds remain invested in supported portfolio-wallet yield sources.
- [Transaction Approvals](https://docs.groundtech.co/docs/portfolio-wallets/transaction-approvals.md): How organization approvals work, when they are required, and what to verify before signing.
- [Polling](https://docs.groundtech.co/docs/portfolio-wallets/polling.md): Examples for scheduled monitoring with list and get endpoints.
- [Webhooks](https://docs.groundtech.co/docs/portfolio-wallets/webhooks.md): Register webhooks and receive real-time Portfolio Wallet events.
- [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.
- [Security](https://docs.groundtech.co/docs/security/custody-model.md): Security reviews, custody model, wallet controls, and deployment references.
- [API Changelog](https://docs.groundtech.co/docs/changelog.md): Breaking changes and notable updates to the Ground API.
- [Contract Addresses](https://docs.groundtech.co/docs/resources/addresses.md): Current production and sandbox contract and program deployments.
- [gtokens](https://docs.groundtech.co/docs/gtokens/introduction.md): Give users access to Ground RWA yield through gtokens or add revenue sharing with a fee wrapper.
- [gtoken quickstart](https://docs.groundtech.co/docs/gtokens/quickstart.md): Discover a sandbox gtoken source, authorize an address, and deposit into its backing vault.
- [Understanding gtokens and fee wrappers](https://docs.groundtech.co/docs/gtokens/concepts.md): Understand the contracts, shares, access controls, and API resources in a gtoken integration.
- [Discover gtoken yield sources](https://docs.groundtech.co/docs/gtokens/discover-yield-sources.md): Use the gtoken catalogue to select a source, backing vault, network, asset, and contract interface.
- [Integrate gtokens directly onchain](https://docs.groundtech.co/docs/gtokens/integrate-directly-onchain.md): Discover a gtoken source, authorize an EVM address, and integrate its backing vault's deposits and withdrawals.
- [Manage gtoken access](https://docs.groundtech.co/docs/gtokens/manage-gtoken-access.md): Authorize, verify, and remove an address for direct deposits into a gtoken backing vault.
- [Deposit and redeem onchain](https://docs.groundtech.co/docs/gtokens/deposit-and-redeem.md): Deposit supported assets to receive gtokens and redeem through synchronous or request/claim vault flows.
- [Configure revenue sharing on gtokens](https://docs.groundtech.co/docs/gtokens/configure-revenue-sharing.md): Have Ground provision a fee wrapper and integrate its customer and fee lifecycle.
- [Manage fee wrappers](https://docs.groundtech.co/docs/gtokens/manage-fee-wrappers.md): Provision, retrieve, and update a fee wrapper over a gtoken's existing backing vault.
- [Manage fee-wrapper access](https://docs.groundtech.co/docs/gtokens/manage-fee-wrapper-access.md): Authorize customer addresses to deposit into an organization fee wrapper.
- [Integrate gtoken webhooks](https://docs.groundtech.co/docs/gtokens/webhooks.md): Receive and verify gtoken access, fee-wrapper, and fee-configuration lifecycle events.
- [Handle asynchronous gtoken operations](https://docs.groundtech.co/docs/gtokens/async-operations.md): Track API submissions, onchain requests, confirmations, processing, and claims without losing state.
- [Test a gtoken integration in sandbox](https://docs.groundtech.co/docs/gtokens/sandbox-testing.md): Validate discovery, access, contract calls, asynchronous operations, and webhooks before production.
- [gtoken contracts](https://docs.groundtech.co/docs/gtokens/contracts.md): Verified gtoken backing vaults and fee-wrapper contracts by environment.
- [MicroVaults](https://docs.groundtech.co/docs/microvaults/introduction.md): Customer-owned onchain vaults with externally held ERC-20 shares.
- [MicroVault quickstart](https://docs.groundtech.co/docs/microvaults/quickstart.md): Create and inspect a sandbox MicroVault.
- [Concepts and control model](https://docs.groundtech.co/docs/microvaults/concepts.md)
- [Supported chains and yield sources](https://docs.groundtech.co/docs/microvaults/supported-chains-and-sources.md)
- [Create a MicroVault](https://docs.groundtech.co/docs/microvaults/create-vault.md): Create a vault and track its deployment.
- [Manage shareholders](https://docs.groundtech.co/docs/microvaults/shareholders.md): Approve or remove wallets that may hold MicroVault shares.
- [Configure strategy and source modes](https://docs.groundtech.co/docs/microvaults/strategy.md): Choose yield sources and set target allocations.
- [Configure fees](https://docs.groundtech.co/docs/microvaults/fees.md): Set management and performance fees and choose who receives fee shares.
- [Subscribe from an external wallet](https://docs.groundtech.co/docs/microvaults/subscribe.md): Approve USDC and mint MicroVault shares from a browser wallet.
- [Redeem MicroVault shares](https://docs.groundtech.co/docs/microvaults/redeem.md): Execute an instant redemption or request underlying liquidation.
- [Export vault authority](https://docs.groundtech.co/docs/microvaults/export-authority.md): Transfer one MicroVault from Ground management to an authority you control.
- [Use emergency controls](https://docs.groundtech.co/docs/microvaults/emergency-controls.md): Pause or resume individual MicroVault operations.
- [Synchronous and asynchronous operations](https://docs.groundtech.co/docs/microvaults/async-operations.md): Understand when an operation settles immediately and when it requires later processing.
- [Statuses, activity, and performance](https://docs.groundtech.co/docs/microvaults/status-and-performance.md)
- [Sandbox testing](https://docs.groundtech.co/docs/microvaults/sandbox-testing.md): Validate the complete MicroVault lifecycle on Ethereum Sepolia.
- [MicroVault contracts](https://docs.groundtech.co/docs/microvaults/contracts.md)
- [Security and trust model](https://docs.groundtech.co/docs/microvaults/security.md)
- [List Portfolio Wallet yield sources](https://docs.groundtech.co/api-reference/list-portfolio-wallet-yield-sources.md): Lists available yield sources for this environment, along with each source's deposit token and current status.
- [Create a portfolio wallet](https://docs.groundtech.co/api-reference/create-wallet.md): Creates a wallet that either invests deposits automatically or keeps them in cash. Reusing `requestId` returns the same wallet.
- [List portfolio wallets](https://docs.groundtech.co/api-reference/list-wallets.md): Returns a cursor-paginated list of wallets for the authenticated organization.
- [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 portfolio wallet](https://docs.groundtech.co/api-reference/get-wallet.md): Returns the wallet with balances, strategy, positions, and deposit addresses.
- [Enable a wallet deposit address](https://docs.groundtech.co/api-reference/enable-wallet-deposit-address.md): Enables Stellar deposits in sandbox or beta-enabled production. Requires organization signing to be enabled.
- [Update a portfolio wallet](https://docs.groundtech.co/api-reference/update-wallet.md): Updates the wallet label.
- [Update wallet strategy](https://docs.groundtech.co/api-reference/update-strategy.md): Updates selected token strategies. Open rebalances keep their reservations; new plans use unreserved funds. Open withdrawals block edits.
- [Preview wallet allocation](https://docs.groundtech.co/api-reference/preview-allocation.md): Checks a proposed movement between cash and yield positions and shows the resulting balances. Moving cash to cash is not supported.
- [Allocate wallet funds](https://docs.groundtech.co/api-reference/allocate.md): Moves settled, unreserved funds between cash and yield. Open rebalances keep reservations and destination commitments; changed plans require a new preview.
- [List deposits](https://docs.groundtech.co/api-reference/list-deposits.md): Lists a wallet's deposits one page at a time. Incoming transfers are not added to the balance until processing finishes.
- [Get a deposit](https://docs.groundtech.co/api-reference/get-deposit.md): Returns a single deposit by its ID.
- [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.
- [Request sandbox mock USDT](https://docs.groundtech.co/api-reference/request-sandbox-usdt.md): Requests mock USDT for an Ethereum Sepolia wallet. Available only in sandbox. Check the request until it is `confirmed` or `failed`.
- [Get a sandbox mock USDT request](https://docs.groundtech.co/api-reference/get-sandbox-usdt-request.md): Returns the current status of a mock USDT faucet transfer owned by the authenticated organization.
- [Preview a withdrawal](https://docs.groundtech.co/api-reference/withdrawal-preview.md): Shows how much can be withdrawn and checks an optional amount, destination, token, and set of source positions.
- [Withdraw funds](https://docs.groundtech.co/api-reference/withdraw.md): Starts a withdrawal. Reusing `requestId` returns the same withdrawal. If automatic rebalancing is off, you can choose the source positions.
- [List withdrawals](https://docs.groundtech.co/api-reference/list-withdrawals.md): Returns a cursor-paginated list of withdrawals for a specific wallet.
- [Get a withdrawal](https://docs.groundtech.co/api-reference/get-withdrawal.md): Returns a single withdrawal by its ID.
- [List pending Turnkey approval activities](https://docs.groundtech.co/api-reference/list-pending-turnkey-activities.md): Lists approval requests that are waiting for the customer, with the related wallet and withdrawal details.
- [Create Turnkey activity approval request](https://docs.groundtech.co/api-reference/create-turnkey-activity-approval-request.md): Creates the Turnkey approval or rejection request that the customer signs before submitting their vote.
- [Vote on Turnkey activity](https://docs.groundtech.co/api-reference/vote-turnkey-activity.md): Submits the customer's signed approval or rejection after Ground checks that it matches the pending Turnkey activity.
- [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.
- [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.
- [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.
- [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.
- [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.
- [List accounting activity](https://docs.groundtech.co/api-reference/list-accounting-activity.md): Shows accounting activity for a wallet or your organization. Records with the same `journalEntryId` are part of the same entry.
- [Get accounting yield period summary](https://docs.groundtech.co/api-reference/get-accounting-yield-period-summary.md): Shows how a wallet or your organization performed over a selected period. Performance values can be negative.
- [Create a webhook](https://docs.groundtech.co/api-reference/create-webhook.md): Creates a webhook for `portfolio_wallet.*` events. The signing secret is shown only once, in this response.
- [List webhooks](https://docs.groundtech.co/api-reference/list-webhooks.md): Lists active webhooks one page at a time. Signing secrets are not included.
- [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.
- [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.
- [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.
- [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 gtoken yield sources](https://docs.groundtech.co/api-reference/list-gtoken-yield-sources.md): Returns the unpaginated integration manifest for existing Ground gtokens.
- [Add an address to a gtoken allowlist](https://docs.groundtech.co/api-reference/add-gtoken-allowlist.md): Allow a wallet using its signed authorization challenge. The verified manager retains removal rights.
- [Check an address's gtoken access](https://docs.groundtech.co/api-reference/get-gtoken-allowlist.md)
- [Get a wallet authorization challenge](https://docs.groundtech.co/api-reference/get-gtoken-allowlist-authorization.md): Get organization-bound EIP-712 typed data to sign for wallet admission. The authorization expires in five minutes.
- [Remove an address from a gtoken allowlist](https://docs.groundtech.co/api-reference/delete-gtoken-allowlist.md)
- [List fee wrappers](https://docs.groundtech.co/api-reference/list-fee-wrappers.md)
- [Provision a fee wrapper](https://docs.groundtech.co/api-reference/create-fee-wrapper.md)
- [Get a fee wrapper](https://docs.groundtech.co/api-reference/get-fee-wrapper.md)
- [Update a fee wrapper's performance fee](https://docs.groundtech.co/api-reference/update-fee-wrapper-fees.md): Update management fees separately from other fee fields. Caps are immutable. Recipient changes are unsupported while management fees are enabled.
- [Add a customer to a fee-wrapper allowlist](https://docs.groundtech.co/api-reference/add-fee-wrapper-allowlist.md)
- [Check a customer's fee-wrapper access](https://docs.groundtech.co/api-reference/get-fee-wrapper-allowlist.md)
- [Remove a customer from a fee-wrapper allowlist](https://docs.groundtech.co/api-reference/delete-fee-wrapper-allowlist.md)
- [Create a gtoken webhook](https://docs.groundtech.co/api-reference/create-gtoken-webhook.md)
- [List gtoken webhooks](https://docs.groundtech.co/api-reference/list-gtoken-webhooks.md)
- [List gtoken webhook events](https://docs.groundtech.co/api-reference/list-gtoken-webhook-events.md)
- [Get a gtoken webhook](https://docs.groundtech.co/api-reference/get-gtoken-webhook.md)
- [Delete a gtoken webhook](https://docs.groundtech.co/api-reference/delete-gtoken-webhook.md)
- [List events for a gtoken webhook](https://docs.groundtech.co/api-reference/list-gtoken-webhook-events-by-webhook.md)
- [List MicroVaults](https://docs.groundtech.co/api-reference/list-microvaults.md): Returns active MicroVaults and creations still provisioning. Use each active vault's `id` in API paths and its `address` for onchain share-token interactions.
- [Create a MicroVault](https://docs.groundtech.co/api-reference/create-microvault.md): Deploys a MicroVault and ERC-20 share token with the selected base asset, token metadata, and fee policy. Returns a task while provisioning.
- [Get a MicroVault](https://docs.groundtech.co/api-reference/get-microvault.md): Returns the vault's identity, share-token metadata, current state, asset balances, and latest NAV observation.
- [List MicroVault yield sources](https://docs.groundtech.co/api-reference/list-microvault-yield-sources.md): Returns the yield sources admitted for MicroVault use on a chain, including APY, processing-time estimates, and synchronous or asynchronous capabilities.
- [List MicroVault source positions](https://docs.groundtech.co/api-reference/list-microvault-sources.md): Returns each source attached to the vault with its permission mode, current position value, APY, and pending or claimable operations.
- [Update MicroVault strategy](https://docs.groundtech.co/api-reference/update-microvault-strategy.md): Sets the vault's target allocation across idle base assets and admitted yield sources. Ground automation subsequently moves assets toward the new targets.
- [Update MicroVault source mode](https://docs.groundtech.co/api-reference/update-microvault-source-mode.md): Controls whether the vault may enter, exit, both, or stop using a source. It does not change the target or erase an existing position.
- [Update MicroVault fees](https://docs.groundtech.co/api-reference/update-microvault-fees.md): Replaces the vault's management fee, performance fee, and fee-share recipient. The complete fee policy must be supplied on every update.
- [Update MicroVault pause controls](https://docs.groundtech.co/api-reference/update-microvault-pause.md): Blocks or restores one vault capability without changing the other pause controls. Use this for incident response or planned operational restrictions.
- [Get MicroVault pause status](https://docs.groundtech.co/api-reference/get-microvault-pause-status.md): Returns which subscription, redemption, transfer, source-entry, and source-exit capabilities are currently paused for the vault.
- [Get MicroVault performance summary](https://docs.groundtech.co/api-reference/get-microvault-performance-summary.md): Returns lifetime investment earnings across the organization's MicroVaults. Use `status` to determine whether every vault was included in the aggregate.
- [Get MicroVault performance series](https://docs.groundtech.co/api-reference/get-microvault-performance-series.md): Returns chronological lifetime-earned, NAV, and trailing-APY observations for charting and performance analysis.
- [List MicroVault activity](https://docs.groundtech.co/api-reference/list-microvault-activity.md): Returns the vault's user-visible money-movement history in reverse chronological order, including current operation status and known transaction hashes.
- [Get MicroVault shareholders](https://docs.groundtech.co/api-reference/get-microvault-shareholders.md): Returns wallets in the current shareholder list and whether the list containing each wallet has been confirmed onchain.
- [Add a MicroVault shareholder](https://docs.groundtech.co/api-reference/add-microvault-shareholder.md): Adds a wallet to the shareholder list so it can subscribe or receive shares after the updated list is confirmed onchain.
- [Remove a MicroVault shareholder](https://docs.groundtech.co/api-reference/remove-microvault-shareholder.md): Removes a wallet from the shareholder list after onchain confirmation. Existing shares are not burned and remain redeemable.
- [Get shareholder proof](https://docs.groundtech.co/api-reference/get-microvault-shareholder-proof.md): Returns the proof an approved wallet uses to subscribe or receive shares. A `404` means no proof exists on the confirmed onchain list.
- [Preview a MicroVault redemption](https://docs.groundtech.co/api-reference/preview-microvault-redemption.md): Returns an instant route when liquidity is available, otherwise a requested route that settles at actual attributable proceeds.
- [Get a requested redemption](https://docs.groundtech.co/api-reference/get-microvault-redemption.md): Returns liquidation progress, actual attributable proceeds, the fixed receiver, and underlying source operations for one asynchronous redemption request.

## OpenAPI Specs

- [swagger-combined](/swagger/swagger-combined.yaml)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.