API reference

Base URL:

https://api.naven.network/v1/agentic-trading

All requests require a server-side Naven Project API key:

Authorization: Bearer naven_api_...

Except for public Strategy discovery, requests also require a user-scoped authorization accepted by the connected trading provider:

X-Trading-Authorization: Bearer ...

This is deliberately separate from the Naven Project API key. Naven forwards the explicit trading authorization to the provider for that request; it does not invent a shared provider identity, require provider-side Naven settings, or forward browser cookies. Provider base URLs remain an adapter implementation detail.

Strategies

Method	Path	Description
`GET`	`/strategies?scope=explore`	List published Strategies available to the Project
`GET`	`/strategies?scope=mine`	List Strategies owned by the Project
`POST`	`/strategies`	Create a Strategy and its first immutable version
`GET`	`/strategies/:strategyId`	Get one visible Strategy
`POST`	`/strategies/:strategyId/versions`	Publish another immutable Strategy version

Strategy definitions are validated by the active strategy-runtime provider. The current provider supports quantitative signal Strategies with instructions, a market universe, data sources, and a candle interval.

Accounts

Method	Path	Description
`GET`	`/accounts`	List execution Accounts for the Project
`POST`	`/accounts/agent-wallets`	Idempotently provision an isolated Agent Wallet

Agent Wallet input:

{
  "name": "Momentum Wallet",
  "idempotencyKey": "wallet:momentum:user-42"
}

idempotencyKey must be stable for one logical wallet-creation attempt.

Runtimes

Method	Path	Description
`GET`	`/runtimes`	List the Project's Strategy Runtimes
`POST`	`/runtimes`	Launch a Runtime
`GET`	`/runtimes/:runtimeId`	Get Runtime configuration and provider state
`PATCH`	`/runtimes/:runtimeId/status`	Set `active`, `paused`, or `stopped`

Runtime input:

{
  "strategyVersionId": "STRATEGY_VERSION_ID",
  "accountId": "ACCOUNT_ID",
  "name": "BTC Momentum Agent",
  "cronExpression": "*/15 * * * *",
  "fundLimitUsd": 1000,
  "maxLeverage": 2,
  "maxDrawdownPercent": 8
}

Executions

Method	Path	Description
`GET`	`/runtimes/:runtimeId/executions`	List up to the latest provider-normalized Execution records
`POST`	`/runtimes/:runtimeId/executions`	Trigger an immediate Execution

An Execution response can contain provider-specific decision and riskAssessment objects. Ownership, trigger, timestamps, lifecycle status, attempt count, normalized order summary, and errors form the stable Naven surface.

Response envelope

Successful and provider-rejected requests use the standard envelope:

{
  "code": 0,
  "message": "ok",
  "data": {}
}

Naven preserves upstream HTTP status codes for validated provider responses. Network errors, timeouts, missing provider configuration, and malformed provider responses return:

{
  "code": 1503,
  "message": "Agentic trading service is unavailable",
  "data": null
}

Current limitations

Public Strategy discovery is the only operation that does not require a trading authorization with the current provider.
The current integration accepts an existing provider user authorization per request; provider-native OAuth or service credentials can replace this without changing resource paths.
Agent Wallet funding is not included in the Runtime creation request.
The active provider determines supported markets, data sources, and venues.
A stopped Runtime cannot be resumed.
Venue-native order endpoints are not exposed.