Partner data models

AdvisorDto

Field	Type	Required	Description
object	string	Yes
as_of	string	Yes
headline	string	Yes
regime	"rising", "falling", "volatile", "stable", "unknown"	Yes
bullets	string[]	Yes	Plain-language findings, each traceable to a computed figure.
top_opportunities	AdvisorOpportunityDto[]	Yes
portfolio	AdvisorPortfolioDto	Yes
disclaimer	string	Yes

AdvisorOpportunityDto

Field	Type	Required	Description
vault_id	string	Yes
name	string	Yes
asset	"USDC", "USDT0"	Yes
risk_adjusted_apy	number	Yes
forecast_apy	number · nullable	Yes
recommendation	"overweight", "neutral", "underweight"	Yes

AdvisorPortfolioDto

Field	Type	Required	Description
current_value	number	Yes
uplift_vs_aave	number	Yes
uplift_vs_aave_pct	number	Yes
positions	number	Yes

ApiKeyOutputDto

Field	Type	Required	Description
id	string	Yes
object	string	Yes
label	string	Yes
secret	string	Yes	Masked secret (full shown only on creation)
prefix	string	Yes
environment	"test", "live"	Yes
scopes	string[]	Yes
partner_id	string · nullable	No
created_at	string	Yes
last_used_at	string · nullable	No
revoked	boolean	Yes

ApyHistoryDto

Field	Type	Required	Description
object	string	Yes
vault_id	string	Yes
name	string · nullable	Yes
asset	"USDC", "USDT0"	Yes
chain	string · nullable	Yes
days	number	Yes
apy_avg	number · nullable	Yes	Mean over the window. null with no observations.
observations	number	Yes
points	ApyHistoryPointDto[]	Yes

ApyHistoryPointDto

Field	Type	Required	Description
t	number	Yes	Epoch ms of the observation.
apy	number	Yes

AttributedUser

Schema: UserRecord & object

BalanceDto

Field	Type	Required	Description
object	string	Yes
user_id	string · nullable	Yes
asset	"USDC", "USDT0"	Yes
principal	number	Yes
current_value	number	Yes
accrued_yield	number	Yes
positions	number	Yes	Active positions folded into this row.

BalanceSnapshotDto

Field	Type	Required	Description
object	string	Yes
date	string	Yes
t	number	Yes	Epoch ms of the day boundary.
principal	number	Yes
value	number	Yes
accrued	number	Yes
positions	number	Yes
users	number	Yes
by_asset	SnapshotAssetDto[]	Yes

CampaignOutputDto

Field	Type	Required	Description
id	string	Yes
object	string	Yes
partner_id	string	Yes
name	string	Yes
slug	string	Yes
utm_source	string · nullable	No
utm_medium	string · nullable	No
status	"active", "paused"	Yes
created_at	string	Yes
updated_at	string	Yes

ChainHealth

Field	Type	Required	Description
key	string	Yes
name	string	Yes
chainId	integer · nullable	Yes
status	"operational", "degraded", "down"	Yes
block_lag_s	number · nullable	Yes
rpc_error	string · nullable	Yes

CreateCampaignInputDto

Field	Type	Required	Description
name	string	Yes
slug	string	No	Unique within partner
utm_source	string	No
utm_medium	string	No

CreateKeyInputDto

Field	Type	Required	Description
label	string	Yes
environment	"test"	No	Only test keys can be created via API. default: test
scopes	"read", "write", "partner:read", "partner:admin"	No	Permitted scopes. Wildcards and keys:admin are not assignable.
partner_id	string	No	Bind key to a partner for scoped access

CreatePartnerInputDto

Field	Type	Required	Description
name	string	Yes
slug	string	No	URL-friendly slug (auto-generated from name if omitted)
contact_email	string	No
webhook_url	string	No
revenue_share_pct	number	No	Revenue share percentage (0–1) default: 0.15
metadata	object	No

CreateUserInputDto

Field	Type	Required	Description
external_id	string	Yes	Your customer id — unique per user.
label	string	No
email	string	No
wallets	string[]	No
metadata	object	No

CreateWebhookInputDto

Field	Type	Required	Description
url	string	Yes
events	string[]	No	Event types, or [""] for all. Default: [""].
active	boolean	No	default: True

DecisionAlternativeDto

Field	Type	Required	Description
vault_id	string	Yes
name	string	Yes
provider	string	Yes
apy	number	Yes
risk_tier	string	Yes

DecisionDto

Field	Type	Required	Description
id	string	Yes
object	string	Yes
at	string	Yes
position_id	string	Yes
user_id	string · nullable	Yes
asset	"USDC", "USDT0"	Yes
type	"initial_routing", "rebalance"	Yes
from_vault	string · nullable	Yes	null for initial_routing.
to_vault	string	Yes
apy_before	number · nullable	Yes
apy_after	number · nullable	Yes
expected_uplift_bps	number · nullable	Yes	apy_after - apy_before, in bps.
reason	string · nullable	No
alternatives	DecisionAlternativeDto[]	Yes	Venues available for this asset at read time.
rationale	string	Yes
status	string	Yes

DeletedResource

Field	Type	Required	Description
id	string	Yes
deleted	boolean	Yes

ErrorEnvelope

Field	Type	Required	Description
error	object	Yes

LedgerEntryDto

Field	Type	Required	Description
id	string	Yes
object	string	Yes
user_id	string · nullable	Yes
position_id	string	Yes
wallet	string	Yes
asset	"USDC", "USDT0"	Yes
vault_id	string	Yes
at	string	Yes
type	"deposit", "withdraw", "close", "accrual"	Yes
amount	number	Yes	Signed: withdrawals and closes are negative.
balance_after	number	Yes	Running balance for this position after the row.
settled	boolean	Yes	false for accrual on an open position — unrealized until it settles on-chain.
ref	string	Yes	Source event id.

ListMetaDto

Field	Type	Required	Description
total	number	Yes	Total rows matching the query, across all pages.
limit	number	Yes	Page size in effect (1-200).
has_more	boolean	Yes
next_cursor	string · nullable	Yes	Pass back as ?cursor= for the next page. null on the last page.

PartnerCreated

Field	Type	Required	Description
partner	PartnerOutputDto	Yes
api_key	object	Yes

PartnerDeposits

Field	Type	Required	Description
object	"partner_deposits"	Yes
partner_id	string	Yes
total	number	Yes
count	integer	Yes
deposits	object[]	Yes

PartnerOutputDto

Field	Type	Required	Description
id	string	Yes
object	string	Yes
name	string	Yes
slug	string	Yes
contact_email	string · nullable	No
webhook_url	string · nullable	No
revenue_share_pct	number	Yes
status	"active", "disabled"	Yes
metadata	object	No
created_at	string	Yes
updated_at	string	Yes

PartnerPoints

Field	Type	Required	Description
object	"partner_points"	Yes
partner_id	string	Yes
total_points	number	Yes
users	object[]	Yes

PartnerPosition

Field	Type	Required	Description
id	string	Yes
object	"position"	Yes
user_id	string	Yes
wallet	string	Yes
asset	string	Yes
chain	string	Yes
vault_id	string	Yes
principal	number	Yes
apy	number	Yes	Annualized rate as a decimal fraction. 0.052 means 5.2%.
strategy	string	Yes
status	string	Yes
last_rebalance_at	string · nullable	Yes	format: date-time
withdrawn_total	number	Yes
opened_at	string	Yes	format: date-time
updated_at	string	Yes	format: date-time
tx_hash	string · nullable	Yes
partner_id	string · nullable	Yes
campaign_id	string · nullable	Yes
current_value	number	Yes
accrued_yield	number	Yes

PartnerSummary

Field	Type	Required	Description
object	"partner_summary"	Yes
partner	object	Yes
users	object	Yes
deposits	object	Yes
tvl	object	Yes
yield	object	Yes
points	object	Yes
revenue	object	Yes
as_of	string	Yes	format: date-time

PartnerSummaryOutputDto

Field	Type	Required	Description
object	string	Yes
partner	object	Yes
users	SummaryUsersDto	Yes
deposits	SummaryDepositsDto	Yes
tvl	SummaryTvlDto	Yes
yield	SummaryYieldDto	Yes
points	SummaryPointsDto	Yes
revenue	SummaryRevenueDto	Yes
as_of	string	Yes

PartnerTvl

Field	Type	Required	Description
object	"partner_tvl"	Yes
partner_id	string	Yes
tvl	number	Yes
breakdown	object[]	Yes

PartnerWithdrawals

Field	Type	Required	Description
object	"partner_withdrawals"	Yes
partner_id	string	Yes
total	number	Yes
count	integer	Yes

PartnerYield

Field	Type	Required	Description
object	"partner_yield"	Yes
partner_id	string	Yes
total_yield	number	Yes
positions	object[]	Yes

ReconciliationReportDto

Field	Type	Required	Description
object	string	Yes
as_of	string	Yes
scope	string	Yes
status	"reconciled", "mismatch", "unavailable"	Yes	"unavailable" when MONITOR_API_URL is unset or monitoring is unreachable.
unavailable_reason	string	No
recorded_total	number	Yes
onchain_total	number · nullable	Yes
discrepancy	number · nullable	Yes
diff_bps	number · nullable	Yes
tolerance_bps	number	Yes	RECONCILIATION_TOLERANCE_BPS.
positions	number	Yes
observed_at	string · nullable	Yes
observed_networks	string[]	Yes
breakdown	ReconciliationRowDto[]	Yes
open_discrepancies	ReconciliationRowDto[]	Yes	Rows past the tolerance.

ReconciliationRowDto

Field	Type	Required	Description
asset	"USDC", "USDT0"	Yes
recorded	number	Yes
onchain	number · nullable	Yes	null when monitoring could not supply this asset.
discrepancy	number · nullable	Yes
diff_bps	number · nullable	Yes	Discrepancy in basis points of the chain balance.
observed	boolean	Yes

RegimeDto

Field	Type	Required	Description
object	string	Yes
as_of	string	Yes
regime	"rising", "falling", "volatile", "stable", "unknown"	Yes	Most cautious classification across assets; "unknown" until enough history exists.
description	string	Yes
per_asset	RegimePerAssetDto[]	Yes

RegimePerAssetDto

Field	Type	Required	Description
asset	"USDC", "USDT0"	Yes
regime	"rising", "falling", "volatile", "stable", "unknown"	Yes
blend_apy	number · nullable	Yes	Allocation-weighted blend, latest observation.
trend_slope_bps_day	number · nullable	Yes
volatility	number · nullable	Yes
observations	number	Yes

RevenueShareOutputDto

Field	Type	Required	Description
object	string	Yes
partner_id	string	Yes
partner_name	string	Yes
revenue_share_pct	number	Yes
protocol_fee_rate	number	Yes
tvl	number	Yes
protocol_blend_apy	number	Yes	Protocol-wide allocation-weighted APY across all active Thesauros vaults. Identical for every partner — only tvl and revenue_share_pct are partner-specific.
annual	RevenueTimescaleDto	Yes
daily	RevenueTimescaleDto	Yes
as_of	string	Yes

RevenueTimescaleDto

Field	Type	Required	Description
yield	number	Yes
protocol_fees	number	Yes
partner_revenue	number	Yes

RevokedApiKey

Field	Type	Required	Description
id	string	Yes
revoked	boolean	Yes

ServiceHealth

Field	Type	Required	Description
id	string	Yes
name	string	Yes
status	"operational", "degraded", "down"	Yes
latency_ms	number · nullable	Yes
detail	string	No

ServiceStatus

Field	Type	Required	Description
object	"status"	Yes
status	"operational", "degraded", "down"	Yes
version	string	Yes
uptime_s	integer	Yes
services	ServiceHealth[]	Yes
chains	ChainHealth[]	Yes
updated_at	string	Yes	format: date-time

SignalDto

Field	Type	Required	Description
object	string	Yes
vault_id	string	Yes
name	string	Yes
provider	string	Yes
asset	"USDC", "USDT0"	Yes
chain	string	Yes
risk_tier	"bluechip", "core", "opportunistic"	Yes
apy	number	Yes	Current APY as a fraction (0.076 = 7.6%).
volatility	number · nullable	Yes	Stddev of observed APY. null while insufficient_history is true — withheld rather than estimated.
trend_slope_bps_day	number · nullable	Yes	Trend in bps/day. null while insufficient_history is true — withheld rather than estimated.
forecast_apy	number · nullable	Yes	7-day extrapolation. null while insufficient_history is true — withheld rather than estimated.
risk_factor	number	Yes	Risk multiplier implied by risk_tier.
risk_adjusted_apy	number	Yes	apy * risk_factor - 0.5 * volatility.
observations	number	Yes	Hourly APY snapshots behind these statistics.
insufficient_history	boolean	Yes	True when fewer than 3 observations exist.
rank	number	Yes	1 = best risk-adjusted venue.
recommendation	"overweight", "neutral", "underweight"	Yes

SnapshotAssetDto

Field	Type	Required	Description
asset	"USDC", "USDT0"	Yes
principal	number	Yes
value	number	Yes
accrued	number	Yes

SummaryDepositsDto

Field	Type	Required	Description
total	number	Yes
count	number	Yes

SummaryPointsDto

Field	Type	Required	Description
total	number	Yes

SummaryRevenueDto

Field	Type	Required	Description
revenue_share_pct	number	Yes
annual_partner_revenue	number	Yes
daily_partner_revenue	number	Yes

SummaryTvlDto

Field	Type	Required	Description
total	number	Yes
breakdown	TvlBreakdownDto[]	Yes

SummaryUsersDto

Field	Type	Required	Description
total	number	Yes

SummaryYieldDto

Field	Type	Required	Description
total	number	Yes

TvlBreakdownDto

Field	Type	Required	Description
asset	string	Yes
tvl	number	Yes
positions	number	Yes

UpdateCampaignInputDto

Field	Type	Required	Description
name	string	No
slug	string	No	Unique within partner
utm_source	string	No
utm_medium	string	No
status	"active", "disabled"	No	Disable a campaign without deleting (soft-disable).

UpdatePartnerInputDto

Field	Type	Required	Description
name	string	No
slug	string	No	URL-friendly slug (auto-generated from name if omitted)
contact_email	string	No
webhook_url	string	No
revenue_share_pct	number	No	Revenue share percentage (0–1) default: 0.15
metadata	object	No
status	"active", "disabled"	No	Disable a partner without deleting (soft-disable). Disabled partners stay in DB for history.

UpdateWebhookInputDto

Field	Type	Required	Description
url	string	No
events	string[]	No
active	boolean	No

UpliftDto

Field	Type	Required	Description
object	string	Yes
as_of	string	Yes
scope	string	Yes
totals	UpliftTotalsDto	Yes
positions	UpliftRowDto[]	Yes

UpliftRowDto

Field	Type	Required	Description
object	string	Yes
position_id	string	Yes
user_id	string · nullable	Yes
asset	"USDC", "USDT0"	Yes
vault_id	string	Yes
principal	number	Yes
current_value	number	Yes
apy	number	Yes
aave_baseline	number · nullable	Yes	Value under the passive baseline venue. null when the asset has no baseline venue.
baseline_provider	string	Yes	Baseline venue provider (ANALYTICS_BASELINE_PROVIDER).
baseline_apy	number · nullable	Yes
hold_baseline	number	Yes	Value had the position stayed in its origin vault.
uplift_vs_aave	number · nullable	Yes
uplift_vs_hold	number	Yes
realized_uplift	number · nullable	Yes	Accrued so far vs the baseline.
projected_uplift_annual	number · nullable	Yes	Today's APY spread annualised over principal.

UpliftTotalsDto

Field	Type	Required	Description
principal	number	Yes
current_value	number	Yes
aave_baseline	number	Yes
hold_baseline	number	Yes
uplift_vs_aave	number	Yes
uplift_vs_hold	number	Yes
uplift_vs_aave_pct	number	Yes
baseline_coverage	number	Yes	Share of positions whose asset has a baseline venue; the rest are excluded from baseline totals.

UsageReport

Field	Type	Required	Description
object	"usage"	Yes
range	"24h", "7d", "30d"	Yes
totals	object	Yes
series	object[]	Yes
top_endpoints	object[]	Yes

UserAttribution

Field	Type	Required	Description
id	string	Yes
object	string	Yes
user_id	string	Yes
partner_id	string	Yes
campaign_id	string · nullable	Yes
source	string	Yes
attributed_at	string	Yes	format: date-time

UserLedgerEvent

Field	Type	Required	Description
id	string	Yes
object	"ledger_entry"	Yes
user_id	string	Yes
position_id	string	Yes
asset	string · nullable	Yes
type	string	Yes
amount	number	Yes
apy	number · nullable	Yes	Annualized rate as a decimal fraction. 0.052 means 5.2%.
vault_id	string · nullable	Yes
note	string · nullable	Yes
at	string	Yes	format: date-time

UserRecord

Field	Type	Required	Description
id	string	Yes
object	"user"	Yes
external_id	string · nullable	Yes
label	string	Yes
email	string · nullable	Yes
wallets	string[]	Yes
status	string	Yes
metadata	object	Yes
created_at	string	Yes	format: date-time
updated_at	string	Yes	format: date-time

VaultDto

Field	Type	Required	Description
object	string	Yes
id	string	Yes
name	string	Yes
provider	string	Yes
asset	"USDC", "USDT0"	Yes
chain	string	Yes
apy	number	Yes	Current APY as a fraction.
apy_7d_avg	number · nullable	Yes	Mean of observed hourly snapshots over 7 days. null until observations exist.
apy_30d_avg	number · nullable	Yes	Same over 30 days.
tvl_usd	number	Yes
capacity_usd	number	Yes
risk_tier	"bluechip", "core", "opportunistic"	Yes
status	"active", "paused"	Yes
allocation_pct	number	Yes

WebhookDelivery

Field	Type	Required	Description
id	string	Yes
object	"delivery"	Yes
webhook_id	string	Yes
partner_id	string	Yes
url	string	Yes
event	string	Yes
payload	object	Yes
signature	string	Yes
status	"delivered", "failed"	Yes
attempts	integer	Yes
at	string	Yes	format: date-time
latency_ms	number	Yes

WebhookEndpoint

Field	Type	Required	Description
id	string	Yes
object	"webhook"	Yes
partner_id	string	Yes
url	string	Yes
events	string[]	Yes
secret	string	Yes	Signing secret, returned once at creation; masked on list and update.
active	boolean	Yes
created_at	string	Yes	format: date-time

WebhookEventTypes

Field	Type	Required	Description
object	"webhook_events"	Yes
events	string[]	Yes

YieldHistory

Field	Type	Required	Description
object	"yield_history"	Yes
scope	"protocol"	Yes
asset	string	Yes
blend_apy	number	Yes	Annualized rate as a decimal fraction. 0.052 means 5.2%.
observations	integer	Yes
history	object[]	Yes
breakdown	object[]	Yes