Core concepts¶

The envelope¶

Meadow uses the same envelope as Photon:

{ "success": true, "data": …, "timestamp": "2026-07-29T12:00:00.000Z" }

Errors are {"success": false, "error": {code, message, category, details?, traceId}, "timestamp"} with codes from the shared error table.

Intents and risk tiers¶

A quote request is an intent: who deposits (userAddress), what (asset, amount — smallest-unit string), where (chain), and the risk appetite:

`riskTier`	Meaning
`conservative`	Only venues rated conservative.
`balanced`	Conservative and balanced venues. (default)
`aggressive`	Any healthy venue.

Optional constraints narrow the auction: minApyBps (reject bids under a floor) and allowedVenues (an allow-list of venue ids).

The auction and net APY¶

Posting an intent opens a sealed-bid auction: each solver privately bids the APY it can deliver plus the settlement plan that achieves it. Bids are scored on

net APY = gross APY − fees − amortized settlement gas

and the best net bid wins. The quote you receive is the winning bid: netApy, grossApy, feeBps, the allocation (venue split in shareBps), the winning solverId, a riskScore, and the settlement txPayload. Sealed bidding means no solver sees rivals' bids — there is no last-look advantage. Details: How the auction works.

Quotes expire¶

A quote is executable until expiresAt (Unix seconds). Depositing an expired quote fails with RESOURCE_001 — re-quote and re-sign. Rates you were quoted are honored within the window, never after it.

Two payload kinds¶

txPayload.kind tells you what you're signing:

eip7702Batch — EVM venues. The authorization + digest pair described below; the batch runs as your account.
hypercoreAction — Hyperliquid Core venues (HLP, HYPE staking). Core actions are gasless and signed directly by you, so there is no authorization and no digest: coreActions carries one entry with the exact action, its nonce, and a ready-to-sign typedData document — pass it to your wallet's signTypedData and send the 65-byte signature as executeSignature on Create a deposit (omit authorization). One signature either way; on Core it's the only one.

The settlement payload and the two signatures (eip7702Batch)¶

txPayload is everything needed to settle as your account:

Field	What it is
`authorization`	The EIP-7702 tuple to sign: `{chainId, address, nonce}` — delegates your EOA to the settlement contract for this transaction.
`executeDigest`	A 32-byte digest of the exact call batch. You sign this raw digest.
`calls`	The batch, human-readable: `{target, value, data}` per call (typically approve + deposit). Display these to the user.
`executeNonce`	Replay protection for the batch.

Two signatures, two jobs: the authorization lets the batch run in your address's context; the digest signature proves you approved these exact calls. The settlement contract verifies the digest signature recovers to your address before executing — a relayer cannot substitute a different batch.

Orders¶

A successful deposit (or withdrawal) returns an order:

relaying ──▶ confirmed
    └──────▶ failed

relaying means the settlement is in flight via Photon (photonTxId links to Photon's record); confirmed carries the executionTxHash. Orders also record kind (deposit or withdraw), the venue, and amounts — see Get an order.

Positions and earnings¶

Positions are read live from chain: your share balance per venue and its current value. Earnings compare current value against your cost basis (what you put in): earnings = value − cost basis, aggregated across positions. Because shares sit in your address, these endpoints are a convenience view — the chain itself is always the authority.