---
title: "Create, resume, heartbeat, or close a session"
method: POST
path: "/v1/agent/session"
tags: ["Session"]
---

# Create, resume, heartbeat, or close a session

`POST /v1/agent/session`

## Request

- Base URL: `https://www.farmdash.one/api`
- URL: `https://www.farmdash.one/api/v1/agent/session`
- Auth: HTTP bearer

Multiplexed endpoint. Set `action` to one of:
`create`, `resume`, `heartbeat`, `close`.
`create` returns a one-time `sessionToken`. All mutating follow-up
actions require `sessionId`, owning `agentAddress`, and `sessionToken`
in the JSON body or the `X-FarmDash-Session-Token` header.
Pioneer+ required.

## Headers

- `X-ClawHub-Skill` string

## Request body

- object
  - `action` 'create' | 'resume' | 'heartbeat' | 'close', required
  - `agentAddress` string: Required for `create`, `resume`, `heartbeat`, and `close`
  - `sessionId` string: Required for `resume`, `heartbeat`, `close`
  - `sessionToken` string: Required for `resume`, `heartbeat`, and `close`; returned only once by `create`
  - `agentMeta` AgentMeta
    - `name` string
    - `version` string
    - `framework` string
    - `capabilities` string[]

## Response `200`

Session action result

- object
  - `ok` boolean
  - `session` AgentSession
    - `id` string
    - `agentAddress` string
    - `status` 'active' | 'paused' | 'halted' | 'expired'
    - `delegation` DelegationRecord
      - `ownerAddress` string
      - `apiWalletAddress` string
      - `verified` boolean
      - `verifiedAt` string, date-time, nullable
    - `autopilot` AutopilotConfig
      - `strategies` string[]
      - `assets` string[]
      - `maxEquityPct` number
      - `rebalanceIntervalMin` integer
      - `autoCompound` boolean
      - `riskPreference` 'conservative' | 'balanced' | 'aggressive'
      - `riskSentinel` RiskSentinelConfig
        - `minHealthFactor` number
        - `minLiquidationBufferPct` number
        - `maxStablecoinDepegPct` number
      - `executionAlpha` ExecutionAlphaConfig
        - `mevSafetyMode` 'strict' | 'balanced'
        - `maxQuoteDecayBps` number
        - `maxGasUsdPerAction` number
        - `requirePositiveNetEdge` boolean
        - `minNetEdgeUsd` number
    - `activePositions` TrackedPosition[]
      - `coin` string
      - `side` 'long' | 'short'
      - `entryPrice` number
      - `size` number
      - `leverage` number
      - `stopLoss` number, nullable
      - `takeProfit` number, nullable
      - `openedAt` string, date-time
      - `strategy` string
      - `unrealizedPnl` number
    - `sessionPnl` number
    - `peakEquity` number
    - `tradeCount` integer
    - `lastHeartbeat` string, date-time
    - `createdAt` string, date-time
    - `expiresAt` string, date-time
    - `agentMeta` AgentMeta
      - `name` string
      - `version` string
      - `framework` string
      - `capabilities` string[]
  - `sessionToken` string: One-time session capability returned only when action is `create`
  - `auth` object
    - `scheme` 'session_capability_v1'
    - `header` 'X-FarmDash-Session-Token'
    - `bodyField` 'sessionToken'
    - `note` string

## Other responses

- `401`: Missing or invalid session capability token
- `402`: Free-tier limit exceeded — x402 payment required
- `403`: Session owner or token verification failed

---

[API](https://skmtc.dev/farmdash/apis/farmdash-agent-api.md) · [All operations](https://skmtc.dev/farmdash/apis/farmdash-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/farmdash/apis/farmdash-agent-api/revisions/96310281f58c?raw)