Sandbox API

Sandbox data models

Field definitions for requests and responses. Nullable fields can contain null; optional fields may be absent.

Advisor

Field	Type	Required	Description
`object`	`"advisor"`	No
`as_of`	`string`	No	format: `date-time`
`headline`	`string`	No
`regime`	`string`	No
`bullets`	`string`[]	No
`top_opportunities`	`object`[]	No
`portfolio`	`object`	No
`disclaimer`	`string`	No

ApiKey

Field	Type	Required	Description
`id`	`string`	Yes
`object`	`"api_key"`	Yes
`label`	`string`	Yes
`secret`	`string`	No	Full secret only on create; masked (tsk_test_...a1b2) on list
`prefix`	`string`	No	First 12 chars of the secret
`environment`	`"test"`, `"live"`	Yes
`created_at`	`string`	Yes	format: `date-time`
`last_used_at`	`['string', 'null']`	No	format: `date-time`
`revoked`	`boolean`	Yes
`scopes`	`string`[]	Yes

Balance

Field	Type	Required	Description
`object`	`"balance"`	No
`user_id`	`['string', 'null']`	No
`asset`	`"USDC"`, `"USDT"`	No
`principal`	`number`	No
`current_value`	`number`	No
`accrued_yield`	`number`	No
`positions`	`integer`	No

BalanceSnapshot

Field	Type	Required	Description
`object`	`"balance_snapshot"`	No
`date`	`string`	No
`t`	`integer`	No	Epoch ms
`principal`	`number`	No
`value`	`number`	No
`accrued`	`number`	No
`positions`	`integer`	No
`users`	`integer`	No
`by_asset`	`object`[]	No

CreateKeyRequest

Field	Type	Required	Description
`label`	`string`	No	Human label for the key
`environment`	`"test"`, `"live"`	No	default: `test`

CreatePositionRequest

Field	Type	Required	Description
`wallet`	`string`	Yes
`asset`	`"USDC"`, `"USDT"`	Yes
`amount`	`number`	Yes
`strategy`	`string`	No	"auto" or a target vault id default: `auto`
`user`	`string`	No	Optional user id (usr_...) or external_id to associate

CreateUserRequest

Field	Type	Required	Description
`external_id`	`string`	Yes	Your customer id (unique)
`label`	`['string', 'null']`	No
`email`	`['string', 'null']`	No	format: `email`
`metadata`	`object`	No
`wallets`	`string`[]	No

CreateWebhookRequest

Field	Type	Required	Description
`url`	`string`	Yes	format: `uri`
`events`	`"*"`, `"position.opened"`, `"position.active"`, `"position.rebalanced"`, `"position.withdrawn"`, `"position.closed"`, `"yield.threshold"`, `"system.status"`[]	No	Defaults to ["*"]
`active`	`boolean`	No	default: `True`

Decision

Field	Type	Required	Description
`object`	`"decision"`	No
`id`	`string`	No
`at`	`string`	No	format: `date-time`
`position_id`	`string`	No
`user_id`	`['string', 'null']`	No
`asset`	`string`	No
`type`	`"initial_routing"`, `"rebalance"`	No
`from_vault`	`['string', 'null']`	No
`to_vault`	`string`	No
`apy_before`	`['number', 'null']`	No
`apy_after`	`number`	No
`expected_uplift_bps`	`['number', 'null']`	No
`reason`	`string`	No
`alternatives`	`object`[]	No
`rationale`	`string`	No
`status`	`string`	No

DeletedWebhook

Field	Type	Required	Description
`id`	`string`	Yes
`object`	`string`	Yes
`deleted`	`boolean`	Yes

Delivery

Field	Type	Required	Description
`id`	`string`	Yes
`object`	`"delivery"`	Yes
`webhook_id`	`string`	No
`url`	`string`	No	Target endpoint URL
`event`	`"position.opened"`, `"position.active"`, `"position.rebalanced"`, `"position.withdrawn"`, `"position.closed"`, `"yield.threshold"`, `"system.status"`	Yes
`payload`	`object`	No	The signed event payload { id, type, created_at, data }
`signature`	`string`	No	t=,v1=<hmac_sha256(secret, t + "." + body)>
`status`	`"delivered"`, `"failed"`	Yes
`attempts`	`integer`	No
`at`	`string`	Yes	format: `date-time`
`latency_ms`	`integer`	No

ErrorEnvelope

Field	Type	Required	Description
`error`	`object`	Yes

LedgerEntry

Field	Type	Required	Description
`id`	`string`	Yes
`object`	`"ledger_entry"`	Yes
`at`	`string`	Yes	format: `date-time`
`user_id`	`['string', 'null']`	No
`position_id`	`string`	Yes
`wallet`	`string`	No
`asset`	`"USDC"`, `"USDT"`	Yes
`type`	`"deposit"`, `"withdraw"`, `"close"`, `"accrual"`	Yes
`amount`	`number`	Yes	Signed delta
`balance_after`	`number`	Yes	Running balance for the position
`vault_id`	`string`	No
`settled`	`boolean`	Yes
`ref`	`string`	No

ListMeta

Field	Type	Required	Description
`total`	`integer`	Yes	Total items matching the filter
`limit`	`integer`	No	Page size applied
`next_cursor`	`['string', 'null']`	No	Opaque cursor for the next page, or null when exhausted

Position

Field	Type	Required	Description
`id`	`string`	Yes
`object`	`"position"`	Yes
`user_id`	`['string', 'null']`	No	Owning end-user, if associated
`wallet`	`string`	Yes
`asset`	`"USDC"`, `"USDT"`	Yes
`chain`	`"base"`, `"arbitrum"`	Yes
`vault_id`	`string`	Yes
`strategy`	`string`	No
`principal`	`number`	Yes
`current_value`	`number`	Yes	principal * (1 + apy * elapsedYears)
`accrued_yield`	`number`	Yes
`apy`	`number`	Yes
`status`	`"active"`, `"closed"`	Yes
`opened_at`	`string`	No	format: `date-time`
`updated_at`	`string`	No	format: `date-time`
`last_rebalance_at`	`['string', 'null']`	No	format: `date-time`
`tx_hash`	`string`	No

PositionEvent

Field	Type	Required	Description
`id`	`string`	Yes
`object`	`"position_event"`	No
`position_id`	`string`	No
`type`	`"deposit"`, `"rebalance"`, `"accrual"`, `"withdraw"`, `"close"`	Yes
`at`	`string`	Yes	format: `date-time`
`amount`	`number`	No
`apy`	`number`	No
`vault_id`	`string`	No
`note`	`string`	No

Rebalance

Field	Type	Required	Description
`id`	`string`	Yes
`object`	`"rebalance"`	Yes
`position_id`	`string`	Yes
`from_vault`	`string`	Yes
`to_vault`	`string`	Yes
`amount`	`number`	No
`reason`	`"yield_optimization"`, `"risk_adjustment"`, `"capacity_rebalance"`	No
`apy_before`	`number`	No
`apy_after`	`number`	No
`at`	`string`	Yes	format: `date-time`
`tx_hash`	`string`	No

Reconciliation

Field	Type	Required	Description
`object`	`"reconciliation"`	Yes
`as_of`	`string`	Yes	format: `date-time`
`scope`	`string`	Yes
`recorded_total`	`number`	Yes
`onchain_total`	`number`	Yes
`discrepancy`	`number`	Yes
`unsettled_yield`	`number`	No
`tolerance`	`number`	No
`status`	`"reconciled"`, `"mismatch"`	Yes
`positions`	`integer`	No
`breakdown`	`object`[]	No

Regime

Field	Type	Required	Description
`object`	`"regime"`	No
`as_of`	`string`	No	format: `date-time`
`regime`	`"rising"`, `"falling"`, `"stable"`, `"volatile"`	No
`description`	`string`	No
`per_asset`	`object`[]	No

RevokedKey

Field	Type	Required	Description
`id`	`string`	Yes
`object`	`string`	Yes
`revoked`	`boolean`	Yes

Signal

Per-vault risk-adjusted signal. APY fields are decimal fractions.

Field	Type	Required	Description
`object`	`"signal"`	No
`vault_id`	`string`	No
`name`	`string`	No
`provider`	`string`	No
`asset`	`"USDC"`, `"USDT"`	No
`chain`	`string`	No
`risk_tier`	`"bluechip"`, `"core"`, `"opportunistic"`	No
`apy`	`number`	No
`volatility`	`number`	No
`trend_slope_bps_day`	`number`	No
`forecast_apy`	`number`	No	Naive 7-day trend forecast (decimal fraction)
`risk_factor`	`number`	No
`risk_adjusted_apy`	`number`	No
`rank`	`integer`	No
`recommendation`	`"overweight"`, `"neutral"`, `"underweight"`	No

Status

Field	Type	Required	Description
`object`	`"status"`	Yes
`overall`	`"operational"`, `"degraded"`, `"outage"`	Yes
`components`	StatusComponent[]	Yes
`incidents`	`object`[]	Yes
`uptime_s`	`integer`	No
`updated_at`	`string`	Yes	format: `date-time`

StatusComponent

Field	Type	Required	Description
`id`	`string`	No
`name`	`string`	No
`status`	`"operational"`, `"degraded"`, `"outage"`	No
`uptime_90d`	`number`	No
`latency_ms`	`integer`	No

UpdateUserRequest

Field	Type	Required	Description
`label`	`['string', 'null']`	No
`email`	`['string', 'null']`	No	format: `email`
`metadata`	`object`	No
`wallets`	`string`[]	No
`status`	`"active"`, `"disabled"`	No

UpliftReport

Field	Type	Required	Description
`object`	`"uplift"`	No
`as_of`	`string`	No	format: `date-time`
`scope`	`string`	No
`totals`	`object`	No
`positions`	UpliftRow[]	No

UpliftRow

Field	Type	Required	Description
`object`	`"uplift_row"`	No
`position_id`	`string`	No
`user_id`	`['string', 'null']`	No
`asset`	`string`	No
`vault_id`	`string`	No
`principal`	`number`	No
`current_value`	`number`	No
`apy`	`number`	No
`aave_baseline`	`number`	No
`baseline_apy`	`number`	No
`hold_baseline`	`number`	No
`uplift_vs_aave`	`number`	No
`uplift_vs_hold`	`number`	No

Usage

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

UsagePoint

Field	Type	Required	Description
`t`	`integer`	No	Epoch ms bucket start
`requests`	`integer`	No
`errors`	`integer`	No
`p50_ms`	`integer`	No
`p99_ms`	`integer`	No

UsageTotals

Field	Type	Required	Description
`requests`	`integer`	No
`errors`	`integer`	No
`p50_ms`	`integer`	No
`p99_ms`	`integer`	No
`unique_keys`	`integer`	No

User

Field	Type	Required	Description
`id`	`string`	Yes
`object`	`"user"`	Yes
`external_id`	`string`	Yes
`label`	`['string', 'null']`	No
`email`	`['string', 'null']`	No
`metadata`	`object`	No
`wallets`	`string`[]	Yes
`status`	`"active"`, `"disabled"`	Yes
`created_at`	`string`	Yes	format: `date-time`
`updated_at`	`string`	No	format: `date-time`

Vault

Field	Type	Required	Description
`id`	`string`	Yes
`object`	`"vault"`	Yes
`name`	`string`	Yes
`provider`	`"aave"`, `"morpho"`, `"compound"`, `"dolomite"`, `"treasury"`	Yes
`asset`	`"USDC"`, `"USDT"`	Yes
`chain`	`"base"`, `"arbitrum"`	Yes
`apy`	`number`	Yes	Decimal fraction (0.052 = 5.2%)
`apy_7d_avg`	`number`	No
`apy_30d_avg`	`number`	No
`tvl_usd`	`number`	No
`capacity_usd`	`number`	No
`risk_tier`	`"bluechip"`, `"core"`, `"opportunistic"`	Yes
`status`	`"active"`, `"paused"`	Yes
`inception_date`	`string`	No	format: `date`
`description`	`string`	No
`allocation_pct`	`number`	No

Webhook

Field	Type	Required	Description
`id`	`string`	Yes
`object`	`"webhook"`	Yes
`url`	`string`	Yes	format: `uri`
`events`	`string`[]	Yes
`secret`	`string`	Yes	whsec_... used to compute Webhook-Signature
`active`	`boolean`	Yes
`created_at`	`string`	Yes	format: `date-time`

WithdrawRequest

Provide a positive amount for a partial withdrawal, or { "all": true } to close.

Field	Type	Required	Description
`amount`	`number`	No
`all`	`boolean`	No

Yield

Field	Type	Required	Description
`object`	`"yield"`	Yes
`asset`	`string`	Yes
`best_apy`	`number`	Yes
`blend_apy`	`number`	Yes	Allocation-weighted blended APY
`blended_30d`	`number`	No
`breakdown`	YieldBreakdown[]	No
`history`	YieldHistoryPoint[]	No

YieldBreakdown

Field	Type	Required	Description
`vault_id`	`string`	No
`name`	`string`	No
`provider`	`string`	No
`apy`	`number`	No
`allocation`	`number`	No

YieldHistoryPoint

Field	Type	Required	Description
`t`	`integer`	No	Epoch ms
`apy`	`number`	No

Build with us.

Bring your product flow. We'll map the integration together.

Discuss your integration