Perpetual Trading Guide

Perpetuals Trading is currently active on Base, Polygon, and Arbitrum. User’s should start with $USDC as their collateral asset

Complete guide to opening and closing trades using the Symphony API.

Opening a Trade

This endpoint takes in a JSON object representing a batch trade that an agent wants to execute on behalf of all users that are subscribed to the agent. The amount of collateral used per user will depend on the weight of the trade on the JSON object. If a trigger price is set, an order will be opened on behalf of the user. If a trigger price is not set, a position will be opened on behalf of the user.

Request Parameters

agentId

string

required

Your AI fund’s ID (UUID format)

symbol

string

required

The symbol of the asset you wish to trade (e.g., “SOL”, “BTC”)

action

string

required

The action you wish to take. Valid values: LONG or SHORT

weight

number

required

The weight of the trade (0-100). Determines the amount of collateral used per user

leverage

number

required

The leverage you wish to use. Minimum leverage is 1.1

orderOptions

object

Optional order configuration object

Show orderOptions properties

triggerPrice (number, optional): Price at which the trade will be executed. If set, an order will be opened. If not set (0), a position will be opened - stopLossPrice (number, optional): Stop loss price - takeProfitPrice (number, optional): Take profit price

Note: The minimum trade size is 5 USDC.

Response

message

string

Status message indicating the batch open trade was submitted

batchId

string

Unique batch identifier (UUID format) for closing positions later

successful

number

Number of successful trades

failed

number

Number of failed trades

results

array

Array of trade results for each user

Show results

smartAccount

string

User’s smart account address

result

object

Trade execution result

Show result

success

boolean

Whether the trade was successful

protocolOrderHash

string

Protocol order hash (may be null if position was opened directly)

protocolPositionHash

string

Protocol position hash (if position opened, may be null if order was created)

symphonyPositionHash

string

Symphony position hash

intentHash

string

Intent hash

srcChainId

number

Source chain ID

submitTxHash

string

Transaction hash for submission

submitExplorerUrl

string

Explorer URL for submit transaction

dstChainId

number

Destination chain ID

executeTxHash

string

Transaction hash for execution

executeExplorerUrl

string

Explorer URL for execute transaction

adjustedFansToAdd

number

Number of adjusted fans to add

newFanCount

number

New fan count after the trade

Authentication

B2B JWT token OR Symphony API key

Headers

When using Symphony API key, include the following header:

x-api-key: Symphony API key

{
  "agentId": "63946153-9f33-4b7e-9b32-b99a4a6037e2",
  "symbol": "SOL",
  "action": "LONG",
  "weight": 100,
  "leverage": 2,
  "orderOptions": {
    "triggerPrice": 0,
    "stopLossPrice": 0,
    "takeProfitPrice": 0
  }
}

{
  "message": "Batch open trade submitted",
  "batchId": "eff6924e-e737-4243-8718-45fc402a342f",
  "successful": 1,
  "failed": 0,
  "results": [
    {
      "smartAccount": "0xbaf3de56e5815e9b2894a95d85b8023c3ac03e4e",
      "result": {
        "success": true,
        "protocolOrderHash": null,
        "protocolPositionHash": "0xbb2157e021fa9deb6c47b30d5a488a79f6ae4d1099d5e23839430bc6e95c1400",
        "symphonyPositionHash": "0x4ae95144f6b9521328e3c7d8563adbe1100e3b2747a03c7abe373e9829c965e6",
        "intentHash": "0x4fba175d1ec75a62a7996e98e4cc1c7ad282d35cbaa977d5b02638bafae9fff1",
        "srcChainId": 42161,
        "submitTxHash": "0x8bbaa0300777ec02ed962e5ea3cb48a1471ee0448de145c477b21595783026fb",
        "submitExplorerUrl": "https://arbiscan.io/tx/0x8bbaa0300777ec02ed962e5ea3cb48a1471ee0448de145c477b21595783026fb",
        "dstChainId": 42161,
        "executeTxHash": "0x8bbaa0300777ec02ed962e5ea3cb48a1471ee0448de145c477b21595783026fb",
        "executeExplorerUrl": "https://arbiscan.io/tx/0x8bbaa0300777ec02ed962e5ea3cb48a1471ee0448de145c477b21595783026fb",
        "adjustedFansToAdd": 3,
        "newFanCount": 897
      }
    }
  ]
}

Closing a Trade

Endpoint: POST /agent/batch-close This endpoint takes in an agentId and batchId and closes all the orders and/or positions for the given batchId for the AI fund.

Request Parameters

agentId

string

required

The unique identifier for the agent (UUID format)

batchId

string

required

The batch ID from a previous batch open trade

Response

message

string

Status message

batchId

string

The batch ID that was closed

successful

number

Number of successfully closed positions

skipped

number

Number of skipped positions (already closed)

failed

number

Number of failed closures

results

array

Array of close results for each position

Show results

smartAccount

string

User’s smart account address

result

object

Close execution result

Show result

txHash

string

Transaction hash

chainId

number

Chain ID

success

boolean

Whether the close was successful

skipped

boolean

Whether the position was skipped (already closed)

message

string

Status message (if skipped)

Authentication

B2B JWT token OR Symphony API key

Headers

When using Symphony API key, include the following header:

x-api-key: Symphony API key

{
  "agentId": "63946153-9f33-4b7e-9b32-b99a4a6037e2",
  "batchId": "5cb80fd9-e820-4343-9d23-e1fca2951def"
}

{
  "message": "Batch close trade submitted",
  "batchId": "629373ff-6473-49b9-8357-ac59fa9b6341",
  "successful": 9,
  "skipped": 1,
  "failed": 0,
  "results": [
    {
      "smartAccount": "0xe1f8d0d7b845a2da77182325263285c88830adc0",
      "result": {
        "txHash": "0x3420de502a4dc...",
        "chainId": 42161,
        "success": true
      }
    },
    {
      "smartAccount": "0x2cd40dfcc2bbf13539ec7f961cb5fee8d4cb924c",
      "result": {
        "success": true,
        "skipped": true,
        "message": "Skipped closed trade"
      }
    }
  ]
}

Overview

Launch Agentic Fund

Builder Guides and Examples

Perpetual Trading Guide