Quickstart

The Agentic Trading API is available to Naven Projects. It uses the same server-side Project API key as Naven Wallets and Events.

Set your Naven API key in the current shell:

export NAVEN_API_KEY="naven_api_..."

Private strategy, Account, Runtime, and Execution operations also require a user-scoped authorization from the connected trading provider:

export TRADING_AUTHORIZATION="Bearer ..."

The trading authorization is issued by the provider's existing user session. Naven forwards it for the current request and does not require any Naven-specific configuration or code changes in the provider. Keep both credentials in a server-side secret store, never in browser code or an agent prompt. Public Strategy discovery does not require trading authorization.

1. Discover a Strategy

curl --request GET \
  --url "https://api.naven.network/v1/agentic-trading/strategies?scope=explore" \
  --header "Authorization: Bearer $NAVEN_API_KEY"

Choose a published Strategy and retain its latest strategyVersionId.

2. Create an Agent Wallet

curl --request POST \
  --url "https://api.naven.network/v1/agentic-trading/accounts/agent-wallets" \
  --header "Authorization: Bearer $NAVEN_API_KEY" \
  --header "X-Trading-Authorization: $TRADING_AUTHORIZATION" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "BTC Momentum Wallet",
    "idempotencyKey": "wallet:btc-momentum:v1"
  }'

Retain the Account id and fund the returned wallet address before enabling live execution. Each non-stopped Runtime requires its own Agent Wallet during the current provider integration.

3. Launch the Runtime

curl --request POST \
  --url "https://api.naven.network/v1/agentic-trading/runtimes" \
  --header "Authorization: Bearer $NAVEN_API_KEY" \
  --header "X-Trading-Authorization: $TRADING_AUTHORIZATION" \
  --header "Content-Type: application/json" \
  --data '{
    "strategyVersionId": "STRATEGY_VERSION_ID",
    "accountId": "ACCOUNT_ID",
    "name": "BTC Momentum Agent",
    "cronExpression": "*/15 * * * *",
    "fundLimitUsd": 1000,
    "maxLeverage": 2,
    "maxDrawdownPercent": 8
  }'

The Runtime begins in the provider-confirmed state returned by the API. Keep the Runtime id for lifecycle and Execution requests.

4. Run immediately

curl --request POST \
  --url "https://api.naven.network/v1/agentic-trading/runtimes/RUNTIME_ID/executions" \
  --header "Authorization: Bearer $NAVEN_API_KEY" \
  --header "X-Trading-Authorization: $TRADING_AUTHORIZATION"

If the Runtime already has an unfinished Execution, the API returns that Execution instead of starting another one.

5. Inspect Executions

curl --request GET \
  --url "https://api.naven.network/v1/agentic-trading/runtimes/RUNTIME_ID/executions" \
  --header "Authorization: Bearer $NAVEN_API_KEY" \
  --header "X-Trading-Authorization: $TRADING_AUTHORIZATION"

Each record may include the strategy decision, risk assessment, normalized order result, error, and completion time.

6. Pause the Agent

curl --request PATCH \
  --url "https://api.naven.network/v1/agentic-trading/runtimes/RUNTIME_ID/status" \
  --header "Authorization: Bearer $NAVEN_API_KEY" \
  --header "X-Trading-Authorization: $TRADING_AUTHORIZATION" \
  --header "Content-Type: application/json" \
  --data '{ "status": "paused" }'

Use active to resume. Use stopped only when the Runtime should become terminal; a stopped Runtime cannot be resumed.