Integrator guides
This companion API lets integrators manage API keys and dashboard members, then read analytics for users and agents attributed to their integrator.
Read the Developer guides first if you haven’t already; they cover authentication and the User and Agent resource models this API builds on.
Authentication
Section titled “Authentication”Read-only integrator details and analytics routes — GET /integrators/v1/{integratorId}, GET /integrators/v1/{integratorId}/users, GET /integrators/v1/{integratorId}/revenue-summary, and GET /integrators/v1/{integratorId}/agents — accept either a SIWE signature from an integrator member or master user, or an active X-Api-Key for that integrator. The key must match the path’s integratorId and pass its configured Origin allowlist, if one is set.
Listing, creating, or deactivating API keys and listing dashboard members require a SIWE signature from an integrator member. Only the master can add or remove dashboard members. A new key’s secret is returned once at creation; later listings expose key metadata only.
On the core API’s createUser endpoint, the wallet signature is still verified; a valid X-Api-Key attributes the new account to its integrator and takes precedence over a referral code in that request. On other signed-in core routes that support optional integrator context, the key does not replace the user’s signature and adds context only if the signed-in user was referred through that integrator; it does not re-attribute other users.
Treat API keys as bearer secrets: keep them server-side and never embed them in browser code. An origin allowlist does not make a key safe to expose.
Why integrate with YieldSeeker?
Section titled “Why integrate with YieldSeeker?”Give your users an automated way to seek yield across supported DeFi vaults while retaining control of their wallets. YieldSeeker configures a revenue-share rate for each integrator and reports its share of eligible platform fees for users attributed to that integrator.
The dashboard and API let you manage access and track referred users, agents, performance, and revenue-share analytics.
To get started, email krishan@yieldseeker.xyz. We can help set up your integration, API access, and revenue-share terms.
Referred users and revenue share
Section titled “Referred users and revenue share”Attribution follows the user’s referrer: referred users are users whose referrerUserId is the integrator’s master user. A dashboard member gets access to integrator data but does not become a referred user.
Revenue summaries report all-time counts, cumulative yield, platform-fee totals, and transaction totals, alongside current holdings, APY percentiles, and the configured revenueShareBps. integratorFeeShareUsd is calculated from collected and owed platform fees; estimated pending fees are reported separately and are not included in that share. These routes provide analytics, not a revenue-share payout.
Each agent in GET /integrators/v1/{integratorId}/agents also carries the same APYs the agent’s owner sees on its snapshot: apy1d, apy7d, apy30d, apy90d, apyAllTime, apyStartDate, and hasEnoughHistory. Show the APYs only once hasEnoughHistory is true; before that they cover too few days to be meaningful. Agents that aren’t yield products (for example Borrow Agents) report 0 and hasEnoughHistory false. deactivatedDate is set once an agent is deactivated, by its user or because it stayed empty; reactivate it to keep its vault selection and other memories instead of creating a new agent.
Vault selection
Section titled “Vault selection”To limit an agent to the vaults a user picked, save one managed memory with POST /v1/users/{userId}/agents/{agentId}/memories and managedRuleType: "ignored_vault", listing the vault addresses in the content (for example Only allocate to these vaults and never to any other vault: 0x4e65fE4DbA92790696d040ac24Aa414708F5c0AB (Aave Base USDC)). This is a core API route, so it needs the user’s SIWE signature; X-Api-Key does not replace it.
- No language model: the vault addresses are read from the content directly.
- Only our vaults count: addresses YieldSeeker doesn’t list for the agent’s chain and asset (another chain, another asset, another provider’s pools) are ignored. Listed vaults autoseek can’t deposit into are skipped when it runs.
- Nothing left means no vault: for example when the user picked only pools YieldSeeker doesn’t offer, the agent exits every vault and keeps its funds idle. Withdrawing to the user is usually better than leaving funds idle.
- Changing it: call the endpoint again to replace the list; deactivate or delete the memory to remove the restriction. The user’s chat agent can’t change it.
- Picking vaults: build the picker from
vault-options, which only returns vaults a new agent can use.
The reference lists the exact routes and schemas generated from the API’s request and response models. This page describes authentication, attribution and vault selection behavior.