Wallets
Per-wallet balances, approval templates, preferences, and terms acceptance.
/v1/wallets/{addr}/balancesUSDC + native gas balance per chain
One entry per requested chain (default: all supported). Amounts are
base-unit strings (USDC 6dp integer string, native in wei);
nativeUsdPrice is the chain's native gas-token USD price in decimal
dollars (null when unavailable). Per-chain error isolation: a failed
RPC marks that chain error: "rpc_error" and never fails the whole
response.
Auth: apikey header
Parameters
| Parameter | Type | Description |
|---|---|---|
addrpathrequired | Address | Wallet address (0x + 40 hex). |
chainsquery | string | CSV of supported chain ids. Defaults to all. |
Responses
| Status | Type | Description |
|---|---|---|
200 | BalancesResponse | Per-chain balances. |
400 | ApiError | Malformed request (bad/missing params). |
429 | ApiError | Rate limit exceeded. Retry-After (seconds) tells you when to retry.
Reads, feedback, and push writes are keyed per IP; create/update/delete
are keyed per wallet+IP; deposit/withdraw/claim calldata is keyed per
strategy+IP. |
/v1/wallets/{addr}/approvalsAllowances toward the proxy + ready-to-sign approve templates
Current USDC and per-vault share-token allowances toward the Earn
contract (the spender), grouped per chain. Each entry carries an
approved flag and, when not approved, a ready-to-sign
approve(spender, amount) template. A share token is approved when
allowance > 0; USDC is approved when allowance >= requiredUsdc.
Allowances and amounts are base-unit strings. Per-chain error
isolation: a failed RPC marks that chain error: "rpc_error" and
never fails the whole response.
Auth: apikey header
Parameters
| Parameter | Type | Description |
|---|---|---|
addrpathrequired | Address | Wallet address (0x + 40 hex). |
chainsquery | string | CSV of supported chain ids. Defaults to all. |
requiredUsdcquery | string | USDC the pending deposit needs, in 6-decimal base units, evaluated against each requested chain's USDC allowance. Default 0 (report-only). |
vaultsquery | string | CSV of chainId:0xaddress vault keys to report. Each key applies
only to its own chain; a requested chain with no listed vaults
still returns its USDC entry. A key targeting a chain outside the
requested set is a 400. Defaults to every approved vault per
chain. |
Responses
| Status | Type | Description |
|---|---|---|
200 | ApprovalsResponse | Approval state and templates, grouped per chain. |
400 | ApiError | Malformed request (bad/missing params). |
429 | ApiError | Rate limit exceeded. Retry-After (seconds) tells you when to retry.
Reads, feedback, and push writes are keyed per IP; create/update/delete
are keyed per wallet+IP; deposit/withdraw/claim calldata is keyed per
strategy+IP. |
500 | ApiError | Internal server error. |
/v1/wallets/{addr}/prefsRead a wallet's preferences (public)
ToS state, global hide list, the approval-banner flag, and the
OpenCover terms signal. Unknown wallets return defaults (empty hide
list, opencover_terms_accepted false). approved is a legacy field
and always true; so is covered_access (covered strategies are open
to every wallet). opencover_terms_accepted is a SOFT wizard signal
only; the hard covered boundary is enforced at strategy create.
Auth: apikey header
Parameters
| Parameter | Type | Description |
|---|---|---|
addrpathrequired | Address | Wallet address (0x + 40 hex). |
Responses
| Status | Type | Description |
|---|---|---|
200 | WalletPrefsResponse | The wallet's preferences. |
400 | ApiError | Malformed request (bad/missing params). |
429 | ApiError | Rate limit exceeded. Retry-After (seconds) tells you when to retry.
Reads, feedback, and push writes are keyed per IP; create/update/delete
are keyed per wallet+IP; deposit/withdraw/claim calldata is keyed per
strategy+IP. |
500 | ApiError | Internal server error. |
/v1/wallets/{addr}/prefsUpdate a wallet's preferences (SIWE prefs.update)
Updates the global hide list and/or the approval-banner flag in one
signed payload. SignedRequest, action prefs.update. The recovered
wallet must equal the path addr or the call fails 403 owner_mismatch.
At least one of hide_vault_key, unhide_vault_key, hide_approval is
required. Hides and unhides merge into the stored list; the full
resulting list is returned.
Hiding a held vault is allowed (it can force-exit positions). The
response then carries an advisory warnings array listing each active
strategy whose eligible pool drops below its max_positions + 1 floor.
Auth: apikey header
Parameters
| Parameter | Type | Description |
|---|---|---|
addrpathrequired | Address | Wallet address (0x + 40 hex). |
Request bodyPrefsUpdateRequest, required
| Field | Type | Description |
|---|---|---|
siwerequired | SiweBlock | A Sign-In-With-Ethereum proof binding the wallet to (action, payload, issuedAt, expirationTime). |
hide_vault_key | string | Vault key to add to the hide list. |
unhide_vault_key | string | Vault key to remove from the hide list. |
hide_approval | boolean | Set the approval-banner dismissal flag. |
Responses
| Status | Type | Description |
|---|---|---|
200 | PrefsUpdateResponse | The merged hide list and the current approval-banner flag. |
400 | ApiError | Malformed request or SIWE block. code is one of: invalid_request,
siwe_missing (no siwe block), siwe_shape (message/signature not
strings), siwe_parse (message does not match the documented line format). |
401 | ApiError | SIWE verification failed. code is one of: siwe_domain (message domain
not allowlisted), siwe_action (statement/action mismatch), siwe_stale
(expired or validity window out of bounds), siwe_payload (payload hash
or resource mismatch: canonicalization drift, a re-serialized body, or
a - path: entry that does not match the request path), siwe_chain
(bad chain id), siwe_recover (signature does not match the claimed
address), siwe_replay (nonce already used: sign a fresh request). |
403 | ApiError | The signing wallet does not match the {addr}
in the path. A wallet may only write its own preferences / ToS state. |
429 | ApiError | Rate limit exceeded. Retry-After (seconds) tells you when to retry.
Reads, feedback, and push writes are keyed per IP; create/update/delete
are keyed per wallet+IP; deposit/withdraw/claim calldata is keyed per
strategy+IP. |
500 | ApiError | Internal server error. |
503 | ApiError | Transient: prefs_read_failed (current prefs could not be read;
nothing was written) or siwe_rpc (signature-verification RPC
failed). Retry. |
/v1/wallets/{addr}/tosRecord a wallet's ToS agreement (SIWE tos_agreement)
Records the wallet's ToS acceptance. SignedRequest, action
tos_agreement; the signature binds terms_url, which is echoed back.
The recovered wallet must equal the path addr or the call fails 403
owner_mismatch.
Auth: apikey header
Parameters
| Parameter | Type | Description |
|---|---|---|
addrpathrequired | Address | Wallet address (0x + 40 hex). |
Request bodyTosRequest, required
| Field | Type | Description |
|---|---|---|
siwerequired | SiweBlock | A Sign-In-With-Ethereum proof binding the wallet to (action, payload, issuedAt, expirationTime). |
terms_url | string (uri) | The ToS URL being agreed to; echoed back in the response. |
Responses
| Status | Type | Description |
|---|---|---|
200 | TosResponse | The recorded agreement. |
400 | ApiError | Malformed request or SIWE block. code is one of: invalid_request,
siwe_missing (no siwe block), siwe_shape (message/signature not
strings), siwe_parse (message does not match the documented line format). |
401 | ApiError | SIWE verification failed. code is one of: siwe_domain (message domain
not allowlisted), siwe_action (statement/action mismatch), siwe_stale
(expired or validity window out of bounds), siwe_payload (payload hash
or resource mismatch: canonicalization drift, a re-serialized body, or
a - path: entry that does not match the request path), siwe_chain
(bad chain id), siwe_recover (signature does not match the claimed
address), siwe_replay (nonce already used: sign a fresh request). |
403 | ApiError | The signing wallet does not match the {addr}
in the path. A wallet may only write its own preferences / ToS state. |
429 | ApiError | Rate limit exceeded. Retry-After (seconds) tells you when to retry.
Reads, feedback, and push writes are keyed per IP; create/update/delete
are keyed per wallet+IP; deposit/withdraw/claim calldata is keyed per
strategy+IP. |
500 | ApiError | Internal server error. |
503 | ApiError | Signature verification could not reach the chain to validate a contract (ERC-1271) wallet. Transient: retry. Only occurs for smart-wallet signers. |
/v1/wallets/{addr}/opencover-termsRecord a wallet's OpenCover terms acknowledgment (SIWE opencover_terms)
Stores the wallet's acknowledgment that it viewed OpenCover's terms
before selecting COVERED in the strategy wizard. SignedRequest; action
opencover_terms (statement Authorize opencover_terms). Unlike the
platform ToS, the FULL signed SIWE message and the raw signature are
PERSISTED as proof (a third party's terms), keyed one-row-per-wallet with
last-write-wins semantics. The addr is in the PATH; the recovered
wallet MUST equal it or the call is a 403 owner_mismatch. The signed
terms_url binds which terms version was acknowledged and is echoed
back. This ack is ENFORCED at covered strategy create (403
covered_terms_required), not merely client-gated.
Auth: apikey header
Parameters
| Parameter | Type | Description |
|---|---|---|
addrpathrequired | Address | Wallet address (0x + 40 hex). |
Request bodyOpencoverTermsRequest, required
| Field | Type | Description |
|---|---|---|
siwerequired | SiweBlock | A Sign-In-With-Ethereum proof binding the wallet to (action, payload, issuedAt, expirationTime). |
terms_url | string (uri) | The OpenCover terms URL being acknowledged; bound into the signature and echoed back. |
Responses
| Status | Type | Description |
|---|---|---|
200 | OpencoverTermsResponse | The recorded acknowledgment. |
400 | ApiError | Malformed request or SIWE block. code is one of: invalid_request,
siwe_missing (no siwe block), siwe_shape (message/signature not
strings), siwe_parse (message does not match the documented line format). |
401 | ApiError | SIWE verification failed. code is one of: siwe_domain (message domain
not allowlisted), siwe_action (statement/action mismatch), siwe_stale
(expired or validity window out of bounds), siwe_payload (payload hash
or resource mismatch: canonicalization drift, a re-serialized body, or
a - path: entry that does not match the request path), siwe_chain
(bad chain id), siwe_recover (signature does not match the claimed
address), siwe_replay (nonce already used: sign a fresh request). |
403 | ApiError | The signing wallet does not match the {addr}
in the path. A wallet may only write its own preferences / ToS state. |
429 | ApiError | Rate limit exceeded. Retry-After (seconds) tells you when to retry.
Reads, feedback, and push writes are keyed per IP; create/update/delete
are keyed per wallet+IP; deposit/withdraw/claim calldata is keyed per
strategy+IP. |
500 | ApiError | Internal server error. |
503 | ApiError | Signature verification could not reach the chain to validate a contract (ERC-1271) wallet. Transient: retry. Only occurs for smart-wallet signers. |