AIMII
https://api.aimii.fun/v1

Aimii API

Create, configure and control Aimii agents programmatically.

Overview

The Aimii API is a REST API for managing your Aimiis. Requests and responses use JSON, and every response wraps its result in a data or error object.

Base URL
https://api.aimii.fun/v1
Format
JSON over HTTPS
Rate limit
120 requests per minute per key

Authentication

Authenticate every request with an API key in the Authorization header. A key acts on behalf of the wallet that created it, and only sees that wallet's Aimiis.

Header
Authorization: Bearer $AIMII_API_KEY

Keep keys on your server. Don't put them in client-side code, URLs or version control. Bot wallet private keys are write-only and are never returned by the API.

API Keys

Create a key for each server or script that calls the API. A key is shown once when you create it, and you can revoke it at any time.

Agents

Create, read, update and delete your Aimiis. Requests sent from this page run against your real account.

Used by Send request on this page. It stays in memory and is cleared when you leave.

List Aimiis

GET/agents

Retrieve the authenticated user’s Aimiis, newest first.

Try request

Add your API key under Agents to authenticate.
Request
curl "https://api.aimii.fun/v1/agents" \
  -H "Authorization: Bearer $AIMII_API_KEY"
Response200 OK
{
  "data": [
    {
      "id": "0199b819-4c2e-7a10-9f3d-2b8e6a51c7d4",
      "name": "Snipi",
      "type": "snipe",
      "status": "configured",
      "bot_wallet_address": "7hRk2mV9qXcLp4ZsT8nYbW3fJdE6uA1gHoN5rCiQ3Kw",
      "appearance": {
        "shape": "bumps",
        "body": "#ec4f7a",
        "eyes": "round"
      },
      "brain": {
        "objective": "Find early launches with strong buyer momentum. Avoid tokens with weak liquidity or suspicious holder concentration.",
        "instructions": "",
        "autonomy": "guided",
        "decision_style": "balanced",
        "decision_frequency": "15s",
        "context": [
          "new_launches",
          "liquidity",
          "holder_distribution"
        ],
        "memory": {
          "enabled": true,
          "window": "24h"
        },
        "tools": [
          "market_data",
          "token_analysis",
          "trade_execution"
        ]
      },
      "strategy": {
        "buyAmount": 0.2,
        "entryDelay": "1s",
        "maxSnipesPerHour": 10
      },
      "risk_config": {
        "risk": {
          "takeProfit": 20,
          "stopLoss": 10
        }
      },
      "created_at": "2026-10-02T09:42:18Z",
      "updated_at": "2026-10-02T09:42:18Z"
    }
  ]
}

Create an Aimii

POST/agents

Create an Aimii. The bot wallet private key is encrypted on the server and is never returned by any endpoint.

Request body

namestringrequired
Display name, up to 32 characters.
typestringrequired
One of snipe, trade, scalp, copytrade or launch.
bot_private_keystringrequired
Base58 private key of a dedicated bot wallet. Write-only.
brainobject
Objective, instructions, autonomy, context, memory and tools. Defaults are used for anything omitted.
strategyobject
Settings for the chosen type.
risk_configobject
Hard limits: risk, sizing and token filters.
appearanceobject
How the Aimii looks.

Try request

Add your API key under Agents to authenticate.
Request
curl -X POST "https://api.aimii.fun/v1/agents" \
  -H "Authorization: Bearer $AIMII_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Snipi",
  "type": "snipe",
  "bot_private_key": "YOUR_BOT_WALLET_PRIVATE_KEY",
  "brain": {
    "objective": "Find early launches with strong buyer momentum. Avoid tokens with weak liquidity or suspicious holder concentration.",
    "autonomy": "guided"
  },
  "strategy": {
    "buyAmount": 0.2,
    "entryDelay": "1s",
    "maxSnipesPerHour": 10
  },
  "risk_config": {
    "risk": {
      "takeProfit": 20,
      "stopLoss": 10
    }
  }
}'
Response201 Created
{
  "data": {
    "id": "0199b819-4c2e-7a10-9f3d-2b8e6a51c7d4",
    "name": "Snipi",
    "type": "snipe",
    "status": "configured",
    "bot_wallet_address": "7hRk2mV9qXcLp4ZsT8nYbW3fJdE6uA1gHoN5rCiQ3Kw",
    "appearance": {
      "shape": "bumps",
      "body": "#ec4f7a",
      "eyes": "round"
    },
    "brain": {
      "objective": "Find early launches with strong buyer momentum. Avoid tokens with weak liquidity or suspicious holder concentration.",
      "instructions": "",
      "autonomy": "guided",
      "decision_style": "balanced",
      "decision_frequency": "15s",
      "context": [
        "new_launches",
        "liquidity",
        "holder_distribution"
      ],
      "memory": {
        "enabled": true,
        "window": "24h"
      },
      "tools": [
        "market_data",
        "token_analysis",
        "trade_execution"
      ]
    },
    "strategy": {
      "buyAmount": 0.2,
      "entryDelay": "1s",
      "maxSnipesPerHour": 10
    },
    "risk_config": {
      "risk": {
        "takeProfit": 20,
        "stopLoss": 10
      }
    },
    "created_at": "2026-10-02T09:42:18Z",
    "updated_at": "2026-10-02T09:42:18Z"
  }
}

Retrieve an Aimii

GET/agents/:id

Retrieve a single Aimii by ID.

Path parameters

idstring (uuid)required
The ID of the Aimii.

Try request

Add your API key under Agents to authenticate.
Request
curl "https://api.aimii.fun/v1/agents/%3Aid" \
  -H "Authorization: Bearer $AIMII_API_KEY"
Response200 OK
{
  "data": {
    "id": "0199b819-4c2e-7a10-9f3d-2b8e6a51c7d4",
    "name": "Snipi",
    "type": "snipe",
    "status": "configured",
    "bot_wallet_address": "7hRk2mV9qXcLp4ZsT8nYbW3fJdE6uA1gHoN5rCiQ3Kw",
    "appearance": {
      "shape": "bumps",
      "body": "#ec4f7a",
      "eyes": "round"
    },
    "brain": {
      "objective": "Find early launches with strong buyer momentum. Avoid tokens with weak liquidity or suspicious holder concentration.",
      "instructions": "",
      "autonomy": "guided",
      "decision_style": "balanced",
      "decision_frequency": "15s",
      "context": [
        "new_launches",
        "liquidity",
        "holder_distribution"
      ],
      "memory": {
        "enabled": true,
        "window": "24h"
      },
      "tools": [
        "market_data",
        "token_analysis",
        "trade_execution"
      ]
    },
    "strategy": {
      "buyAmount": 0.2,
      "entryDelay": "1s",
      "maxSnipesPerHour": 10
    },
    "risk_config": {
      "risk": {
        "takeProfit": 20,
        "stopLoss": 10
      }
    },
    "created_at": "2026-10-02T09:42:18Z",
    "updated_at": "2026-10-02T09:42:18Z"
  }
}

Update an Aimii

PATCH/agents/:id

Update an Aimii’s configuration. Only the fields you send are changed.

Path parameters

idstring (uuid)required
The ID of the Aimii.

Request body

namestring
New display name.
statusstring
configured or paused.
brainobject
Partial brain settings.
strategyobject
Partial strategy settings.
risk_configobject
Partial risk settings.
appearanceobject
Full appearance object.

Try request

Add your API key under Agents to authenticate.
Request
curl -X PATCH "https://api.aimii.fun/v1/agents/%3Aid" \
  -H "Authorization: Bearer $AIMII_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "paused",
  "risk_config": {
    "risk": {
      "stopLoss": 8
    }
  }
}'
Response200 OK
{
  "data": {
    "id": "0199b819-4c2e-7a10-9f3d-2b8e6a51c7d4",
    "name": "Snipi",
    "type": "snipe",
    "status": "paused",
    "bot_wallet_address": "7hRk2mV9qXcLp4ZsT8nYbW3fJdE6uA1gHoN5rCiQ3Kw",
    "appearance": {
      "shape": "bumps",
      "body": "#ec4f7a",
      "eyes": "round"
    },
    "brain": {
      "objective": "Find early launches with strong buyer momentum. Avoid tokens with weak liquidity or suspicious holder concentration.",
      "instructions": "",
      "autonomy": "guided",
      "decision_style": "balanced",
      "decision_frequency": "15s",
      "context": [
        "new_launches",
        "liquidity",
        "holder_distribution"
      ],
      "memory": {
        "enabled": true,
        "window": "24h"
      },
      "tools": [
        "market_data",
        "token_analysis",
        "trade_execution"
      ]
    },
    "strategy": {
      "buyAmount": 0.2,
      "entryDelay": "1s",
      "maxSnipesPerHour": 10
    },
    "risk_config": {
      "risk": {
        "takeProfit": 20,
        "stopLoss": 8
      }
    },
    "created_at": "2026-10-02T09:42:18Z",
    "updated_at": "2026-10-02T09:42:18Z"
  }
}

Delete an Aimii

DELETE/agents/:id

Permanently delete an Aimii and its encrypted bot wallet key.

Path parameters

idstring (uuid)required
The ID of the Aimii.

Try request

Add your API key under Agents to authenticate.
Request
curl -X DELETE "https://api.aimii.fun/v1/agents/%3Aid" \
  -H "Authorization: Bearer $AIMII_API_KEY"
Response200 OK
{
  "data": {
    "id": "0199b819-4c2e-7a10-9f3d-2b8e6a51c7d4",
    "deleted": true
  }
}

Retrieve state

GET/agents/:id/state

What the Aimii is doing right now: observing, evaluating, waiting or paused.

Path parameters

idstring (uuid)required
The ID of the Aimii.

Coming soon. This endpoint is documented ahead of the agent runtime and returns not_found until then.

Request
curl "https://api.aimii.fun/v1/agents/%3Aid/state" \
  -H "Authorization: Bearer $AIMII_API_KEY"
Response200 OK
{
  "data": {
    "state": "observing",
    "focus": "Watching new launches with rising buyer activity",
    "last_decision": {
      "type": "skipped",
      "reason": "Entry rejected because liquidity was below your minimum."
    }
  }
}

List activity

GET/agents/:id/activity

Observations and decisions, newest first, each with a short reason.

Path parameters

idstring (uuid)required
The ID of the Aimii.

Coming soon. This endpoint is documented ahead of the agent runtime and returns not_found until then.

Request
curl "https://api.aimii.fun/v1/agents/%3Aid/activity" \
  -H "Authorization: Bearer $AIMII_API_KEY"
Response200 OK
{
  "data": [
    {
      "type": "risk_blocked",
      "message": "Daily loss limit reached. No new entries until tomorrow.",
      "created_at": "2026-10-02T14:03:11Z"
    }
  ]
}

Update brain

PATCH/agents/:id/brain

Change how the Aimii thinks without touching its strategy or hard limits.

Path parameters

idstring (uuid)required
The ID of the Aimii.

Coming soon. This endpoint is documented ahead of the agent runtime and returns not_found until then.

Request
curl -X PATCH "https://api.aimii.fun/v1/agents/%3Aid/brain" \
  -H "Authorization: Bearer $AIMII_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "objective": "Only enter launches with very high buyer momentum.",
  "autonomy": "autonomous"
}'
Response200 OK
{
  "data": {
    "objective": "Find early launches with strong buyer momentum. Avoid tokens with weak liquidity or suspicious holder concentration.",
    "instructions": "",
    "autonomy": "autonomous",
    "decision_style": "balanced",
    "decision_frequency": "15s",
    "context": [
      "new_launches",
      "liquidity",
      "holder_distribution"
    ],
    "memory": {
      "enabled": true,
      "window": "24h"
    },
    "tools": [
      "market_data",
      "token_analysis",
      "trade_execution"
    ]
  }
}

Pause

POST/agents/:id/pause

Stop observing and acting. Open positions keep their exit rules.

Path parameters

idstring (uuid)required
The ID of the Aimii.

Coming soon. This endpoint is documented ahead of the agent runtime and returns not_found until then.

Request
curl -X POST "https://api.aimii.fun/v1/agents/%3Aid/pause" \
  -H "Authorization: Bearer $AIMII_API_KEY"
Response200 OK
{
  "data": {
    "id": "0199b819-4c2e-7a10-9f3d-2b8e6a51c7d4",
    "status": "paused"
  }
}

Resume

POST/agents/:id/resume

Start observing again with the current configuration.

Path parameters

idstring (uuid)required
The ID of the Aimii.

Coming soon. This endpoint is documented ahead of the agent runtime and returns not_found until then.

Request
curl -X POST "https://api.aimii.fun/v1/agents/%3Aid/resume" \
  -H "Authorization: Bearer $AIMII_API_KEY"
Response200 OK
{
  "data": {
    "id": "0199b819-4c2e-7a10-9f3d-2b8e6a51c7d4",
    "status": "configured"
  }
}

Errors

Errors use standard HTTP status codes and return a machine-readable code with a human-readable message.

Error response
{
  "error": {
    "code": "unauthorized",
    "message": "A valid API key is required."
  }
}
Error codes
StatusCodeMeaning
400invalid_requestThe request body or parameters are invalid.
401unauthorizedThe API key is missing, invalid or revoked.
404not_foundThe Aimii does not exist or belongs to another wallet.
429rate_limitedToo many requests. Wait for the Retry-After seconds.
500internal_errorSomething went wrong on our side.