Integration contract

Stable, versioned contract for any consumer (XEL, GEN, others).
Identity = wallet address only. Consumers map their own IDs → wallet outside DAY.


Site	https://dayprotocol.com
Docs	https://docs.dayprotocol.com
API base	`https://dayprotocol.com/api/v1`
OpenAPI	https://dayprotocol.com/api/v1/openapi.json
Auth	`X-API-Key` (owner / agent / keeper allowlists). Never `X-Role`.
Route catalog	44-route-catalog.md
Human reference	02-agent-api.md

1. Status codes

HTTP	Meaning	When
200	Done	Intended action applied (reads; harvest with gross applied; etc.)
202	Prepared	Plan ready, not broadcast (phase-1 prepare-only)
422	Blocked	Valid request that cannot be fulfilled (`outcome: "blocked"`, `blockers[]`)
401	Unauthorized	Missing/invalid API key
403	Forbidden	Wrong role or `WALLET_SCOPE`
404	Not found	Unknown resource
429	Rate limited	Back off

Clients branch on the status line, then read the body for detail. Annotated bodies include outcome + httpStatus.

2. Error + blocker enum

Catalog: GET /api/v1/day/errors
Envelope: { schemaVersion, code, message, retryable, blockers:[{code,detail?}] }
Stability: renaming a code is a breaking change; new codes may be added.

3. Read / metrics (wallet-keyed)

Method	Path	Auth
GET	`/api/v1/wallets/{address}/position`	owner\|agent
GET	`/api/v1/wallets/{address}/portfolio`	owner\|agent
GET	`/api/v1/wallets/{address}/performance`	owner\|agent
GET	`/api/v1/wallets/{address}/funding`	owner\|agent
POST	`/api/v1/wallets/batch/positions`	owner\|agent
GET	`/api/v1/day/venues/apy`	public

Every metric response includes asOf and freshness (live / stale / mixed / unavailable).
APY rule: null / unavailable when live read fails — never fabricate.

4. Money surface (wallet-keyed)

Method	Path	Auth
POST	`/api/v1/wallets/{address}/preview`	owner\|agent
POST	`/api/v1/wallets/{address}/route`	owner
POST	`/api/v1/wallets/{address}/harvest`	permissionless
POST	`/api/v1/wallets/{address}/withdraw`	owner
POST	`/api/v1/wallets/{address}/auto-pay`	owner
POST	`/api/v1/wallets/{address}/rebalance`	owner
GET/PUT	`/api/v1/wallets/{address}/auto-yield`	owner\|agent / owner

Legacy /api/v1/characters/{id}/… may still resolve as aliases — do not use in new clients.

5. Discovery / strategies (venue-agnostic)

GET /api/v1/day/strategies (or /venues) — bare ids: suilend, navi, scallop, kamino, jito, marginfi, aave-v3, morpho-blue, …
GET /api/v1/day/venues/apy — live or null
POST /api/v1/day/strategies/deposit/plan — same shape for every strategy
Wallet preview → route → position/performance → harvest → withdraw
Optional webhooks for lifecycle

Fees: 0 bps principal · 500 bps yield skim at harvest · swap fee default 100 bps disclosed in plans.

6. Multi-chain honesty

Homes	Label	Meaning
Sui, Solana	Executable	Phase-1 route homes
Base, Arbitrum	Map	Discovery / prepare; broadcast off until explicit GO + writeReady

GET /api/v1/day/packages — Map vs Executable labels
GET /api/v1/day/base/enablement · /arbitrum/enablement — never imply live write on stubs
Wallet balances: /day/{sui,solana,base,arbitrum}/wallet-balance?address=

7. Swaps & bridge (prepare-only)

Path	Notes
`POST /api/v1/day/jupiter/plan`	Solana
`POST /api/v1/day/turbos/plan`	Sui
`POST /api/v1/day/evm/swap/plan`	Base/Arb
`POST /api/v1/day/bridge/plan`	Mayan Sui↔Sol (+ fee/risk disclosure)
`POST /api/v1/day/bridge/delivery`	Credit only after proof
`POST /api/v1/day/bridge/rescue`	Destination locked to owner

Autopilot decide is within-chain only — never silent cross-chain rebalance.

8. Webhooks

Subscribe: POST /api/v1/day/webhooks → hmacKey once.
Events: deposit.settled, withdraw.settled, harvest.completed, bridge.delivered, bridge.failed, position.updated, apy.updated.
HMAC-SHA256: t.<body> → header X-DAY-Signature: t=…,v1=….
Replay: GET /api/v1/day/webhooks/events.

9. Cage (Base / Arbitrum)

Six actions: ROUTE · EXIT · REBALANCE · HARVEST · COMPOUND · AUTOPAY.
Owner signs; Day never holds keys; destination-lock on venues/payees/owner.

10. curl quickstart

export BASE=https://dayprotocol.com/api/v1
export KEY=$DAY_OWNER_API_KEY
export W=0xYOUR_WALLET

curl -sS "$BASE/day/status" | jq .
curl -sS "$BASE/day/errors" | jq '.enumVersion'
curl -sS "$BASE/day/venues/apy" | jq '.venues[:3]'
curl -sS -H "X-API-Key: $KEY" "$BASE/wallets/$W/portfolio" | jq .
curl -sS -X POST -H "X-API-Key: $KEY" -H 'content-type: application/json' \
  -d "{\"wallets\":[\"$W\"]}" "$BASE/wallets/batch/positions" | jq .

11. OpenAPI lockstep

Live: GET /api/v1/openapi.json
Gate: npm run check:docs-openapi in the day repo
Never ship docs that still say Bearer-as-role, composite strategy ids, or character as primary identity