Skip to main content
Ground makes it easy to identify the right blend of yield sources to configure for a portfolio wallet given target APY, withdrawal processing time requirements, and other constraints. This tutorial shows how to use POST /v2/wallets/quote to turn the requirements for your use case into a set of optimal yield source positions you can use to create a Portfolio Wallet. Yield sources are the underlying yield opportunities (e.g. resolv-lp, syrup-usdc, usdz). A strategy is a combination of allocations across one or more yield sources. The key idea: you tell us what you care about (APY vs withdrawal speed), and we return a small set of optimal allocations. For a given set of requirements, this endpoint will return a set of positions where each option represents a best-possible tradeoff, meaning there is no alternative that both withdraws faster and earns a higher APY at the same time.

​
What the /quote endpoint does

  • Input: high-level constraints and preferences (e.g. “at least 40% instant liquidity” and/or “at least 5% blended APY”).
  • Output: an array of quote options, each with a positions[] allocation (percentages sum to 100) and a predicted blended rate.
When the inputs can be satisfied exactly, you’ll get a single option with constraintsSatisfied: true. When the inputs can’t all be satisfied at once, you still get 200 OK with multiple Pareto-optimal options that make the trade-off explicit (optimize for either APY or LIQUIDITY).

​
Before you start: use the yield source catalog

The quote engine only allocates across yield sources that exist in the yield source catalog:
  • GET /v2/wallets/yield-sources (preferred)
For a deeper breakdown of sources, see Available Yield Sources.

​
Step 1: Decide what to optimize for

Most integrations start from one (or both) of these product requirements:
  • Yield: “I want at least X blended APY.”
  • Withdrawal speed: “I need at least Y% of funds withdrawable within Z time.”
You encode these as quote inputs.

​
Liquidity constraints (withdrawal speed)

If you need a minimum percentage of capital to be instantly withdrawable, include a liquidity constraint in your quote request: 
{
  "liquidityConstraints": [
    { "maxProcessingTime": "PT0H", "minWeightBps": 4000 }
  ]
}
Notes:
  • maxProcessingTime is an ISO 8601 duration (e.g. PT0H for instant, PT24H for up to 24 hours).
  • minWeightBps is in bps out of 10,000 (so 4000 means 40%).

​
Yield targets

To ask for a minimum blended APY, include minApyTargetBps (bps): 
{ "minApyTargetBps": 500 }

​
Step 2: Call POST /v2/wallets/quote

Request fields:
FieldRequiredDescription
requestIdYesUUID v4 idempotency key
minApyTargetBpsNoMinimum blended APY in bps
liquidityConstraintsNoArray of { maxProcessingTime, minWeightBps }
yieldSourceTypesNoFilter by internal yield source type
exclusionsNoExclude yield sources by ID
withdrawalDestinationNo{ destinationChain, destinationToken } — attaches per-position withdrawal time estimates
cURL
curl -X POST "$BASE_URL/v2/wallets/quote" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "minApyTargetBps": 500,
    "liquidityConstraints": [
      { "maxProcessingTime": "PT0H", "minWeightBps": 4000 }
    ],
    "exclusions": [],
    "requestId": "c3353fff-87cf-4c7c-b68c-2700139dd4e6"
  }'

​
Step 3: Evaluate the response (Pareto-optimal options)

The response is an array of quote options. Each option is one Pareto-optimal point:
  • positions[]: allocations with yieldSourceId, name, and pct (percentages sum to 100)
  • blendedRateBps: predicted blended APY for the option (bps)
  • constraintsSatisfied: whether the option satisfies all requested constraints

​
Example: constraints satisfied (single recommendation)

You’ll often get a single option with constraintsSatisfied: true: 
[
  {
    "positions": [
      {
        "yieldSourceId": "resolv-lp",
        "name": "Resolv LP",
        "currentApy": 455,
        "pct": 40,
        "maxProcessingTime": "PT24H"
      },
      {
        "yieldSourceId": "syrup-usdc",
        "name": "Syrup USDC",
        "currentApy": 453,
        "pct": 60,
        "maxProcessingTime": "PT24H"
      }
    ],
    "blendedRateBps": 454,
    "constraintsSatisfied": true
  }
]

​
Example: constraints cannot be met (still 200 OK)

Quotes always return 200 OK with an array of options. If the quote engine can’t find an allocation that satisfies all inputs, you’ll get multiple Pareto-optimal options that trade off yield vs liquidity. In this scenario, the customer wants at least 50% instant liquidity (PT0H) and a minimum blended APY target, but those requirements can’t be met simultaneously. The response includes:
  • one option that optimizes for APY
  • one option that optimizes for LIQUIDITY (withdrawal speed)
[
  {
    "optimizationMode": "APY",
    "positions": [
      {
        "yieldSourceId": "resolv-lp",
        "name": "Resolv LP",
        "currentApy": 455,
        "pct": 100,
        "maxProcessingTime": "PT24H"
      }
    ],
    "blendedRateBps": 455,
    "constraintsSatisfied": false
  },
  {
    "optimizationMode": "LIQUIDITY",
    "positions": [
      {
        "yieldSourceId": "usdz",
        "name": "T-Bills (M0)",
        "currentApy": 330,
        "pct": 100,
        "maxProcessingTime": "PT0H"
      }
    ],
    "blendedRateBps": 330,
    "constraintsSatisfied": false
  }
]
Interpretation:
  • If you pick the APY option, you maximize blended yield but accept slower withdrawals.
  • If you pick the LIQUIDITY option, you meet your desired withdrawal speed but accept a lower blended yield.

​
Step 4: create a wallet using the chosen positions

Pick the option you want, then pass its allocations into the strategy.allocations array when calling POST /v2/wallets. Notes:
  • Each allocation uses yieldSourceId (from the quote’s positions[].yieldSourceId) and pct (percentage, summing to 100).
  • Extra per-position fields from quotes (like currentApy, name, and maxProcessingTime) are informational and not passed to the create endpoint.