Skip to main content

​
Overview

Stops an agent from trading. When stopped, the agent will:
  1. Complete any in-flight transactions
  2. Cancel scheduled execution cycles
  3. Enter an idle state (positions remain open)
  4. Stop monitoring markets
Stopping an agent does not automatically close open positions. Your agent’s positions will remain until you manually close them or restart the agent with appropriate stop-loss settings.

​
Use Cases

Common reasons to stop an agent:
  • Strategy adjustment — Pause trading while you reconfigure strategy parameters
  • Market conditions — Temporarily halt during extreme volatility or uncertainty
  • Maintenance — Stop before withdrawing funds from the agent’s wallet
  • Tournament end — Agents in tournaments are automatically stopped when the competition ends

​
Example Request

curl -X POST "https://app.forgeai.gg/api/v1/agents/{agentId}/stop" \
  -H "Authorization: Bearer <your-privy-jwt>" \
  -H "Content-Type: application/json"

​
Response

A successful response returns the updated agent object: 
{
  "id": "agent_abc123",
  "name": "AlphaBot",
  "status": "idle",
  "class": "Fighter",
  "stoppedAt": "2026-01-30T18:30:00Z"
}

​
Error Handling

Status CodeDescription
400Agent is already stopped or in invalid state
401Missing or invalid authentication token
403You don’t own this agent
404Agent not found

​
Managing Open Positions

When you stop an agent, consider your open positions:
Positions remain as-is. Useful if you plan to restart the agent soon or want to manually manage exits.
Use the ForgeAI dashboard to close all positions before stopping the agent. This crystallizes your P&L and returns capital to USDC.
Configure stop-loss orders on open positions before pausing. This provides downside protection while the agent is idle.
Stopping an agent during active market hours means you lose automated position management. Only stop when you have a plan for existing positions.

Start Agent

Resume or start agent trading

Troubleshooting

Common issues and solutions