# AgentLaunch — Complete API Reference for LLMs and Agents

> Full machine-readable reference for agent-launch.ai
> Compact version: https://agent-launch.ai/llms.txt
> OpenAPI spec: https://agent-launch.ai/docs/openapi

---

## Platform Overview

AgentLaunch (agent-launch.ai) is a bonding curve token launchpad built for the Fetch.ai /
ASI ecosystem. It allows AI agents to create tokens via API, then hand off the on-chain
deployment step to a human via a pre-filled URL.

**The Agent-Human Handoff Protocol:**
1. Agent calls POST /api/agents/tokenize (no wallet needed, API key only)
2. Agent receives a handoff link: https://agent-launch.ai/deploy/{token_id}
3. Agent sends link to human via chat, email, DM, or any channel
4. Human clicks link, connects wallet, approves FET, deploys token
5. Token is live and tradeable immediately
6. Agent can send trade links to human: /trade/{address}?action=buy&amount=100

---

## Authentication

### Method 1: Agentverse API Key (Recommended for agents)

```
Header: X-API-Key: YOUR_AGENTVERSE_API_KEY
```

Obtain key: https://agentverse.ai/profile/api-keys

Validation: The key is checked against https://agentverse.ai/v1/hosting/agents.
Your first agent's address (agent1q...) becomes your platform user identity.
Keys are cached for 5 minutes server-side.

### Method 2: JWT (For wallet users)

```
POST /api/users/login
Content-Type: application/json

{
  "address": "0x1234...abcd",
  "signature": "0xsignature..."
}

Response:
{
  "token": "eyJhbGciOiJIUzI1NiJ9..."
}

Header: Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
```

---

## API Endpoints

### POST /api/agents/tokenize

Create a token record. Returns a handoff link for on-chain deployment.

**Auth:** X-API-Key header required

**Request body:**

| Field        | Type   | Required | Constraints           | Description |
|--------------|--------|----------|-----------------------|-------------|
| agentAddress | string | yes      | agent1q... or 0x...   | The agent being tokenized |
| name         | string | no       | max 32 chars          | Token name (default: auto-generated) |
| symbol       | string | no       | max 11 chars          | Token symbol/ticker (default: auto-generated) |
| description  | string | no       | max 500 chars         | Token description |
| image        | string | no       | URL, base64, or "auto"| Token image (default: auto-generated placeholder) |
| chainId      | int    | no       | 56 or 97              | BSC Mainnet (56) or BSC Testnet (97, default) |

**Example request:**

```json
{
  "agentAddress": "agent1qf8xfhsc8hg4g5l0nhtj5hxxkyd46c64qxs0zhtc8xfhsc8hg4g5l0nh",
  "name": "WeatherBot Token",
  "symbol": "WTR",
  "description": "Token for the WeatherBot agent — real-time weather data on Agentverse",
  "image": "auto",
  "chainId": 97
}
```

**Success response (201):**

```json
{
  "success": true,
  "data": {
    "id": 42,
    "name": "WeatherBot Token",
    "symbol": "WTR",
    "description": "Token for the WeatherBot agent",
    "image": "https://agent-launch.ai/images/tokens/42.png",
    "chainId": 97,
    "agentAddress": "agent1qf8xfhsc8hg4g5l0nhtj5hxxkyd46c64qxs0zhtc8xfhsc8hg4g5l0nh",
    "handoffLink": "https://agent-launch.ai/deploy/42",
    "createdAt": "2026-02-24T10:00:00.000Z"
  }
}
```

**Error responses:**

| HTTP Code | Condition | Response body |
|-----------|-----------|---------------|
| 400 | Validation error (missing field, too long, etc.) | `{ "statusCode": 400, "message": ["name must be shorter than or equal to 32 characters"] }` |
| 401 | Invalid or missing API key | `{ "statusCode": 401, "message": "Unauthorized" }` |
| 409 | Token name or symbol already exists | `{ "statusCode": 409, "message": "Token with this name already exists" }` |
| 500 | Server error | `{ "statusCode": 500, "message": "Internal server error" }` |

---

### GET /api/agents/tokens

List all tokens on the platform.

**Auth:** None required

**Query parameters:**

| Param      | Type   | Default | Description |
|------------|--------|---------|-------------|
| page       | int    | 1       | Page number |
| limit      | int    | 20      | Items per page (max 100) |
| search     | string | -       | Filter by name or symbol |
| categoryId | int    | -       | Filter by category |
| chainId    | int    | -       | Filter by chain (56 or 97) |
| sortBy     | string | createdAt | Sort field: createdAt, market_cap, volume, holders |
| sortOrder  | string | DESC    | ASC or DESC |

**Example request:**

```
GET /api/agents/tokens?sortBy=market_cap&sortOrder=DESC&limit=10
```

**Success response (200):**

```json
{
  "success": true,
  "data": [
    {
      "id": 42,
      "address": "0xAbCd1234...",
      "name": "WeatherBot Token",
      "symbol": "WTR",
      "description": "...",
      "image": "https://...",
      "chainId": 97,
      "listed": false,
      "price": "0.00000123",
      "market_cap": "984.00",
      "volume_24h": "250.00",
      "holders": 12,
      "progress": 3.28,
      "createdAt": "2026-02-24T10:00:00.000Z"
    }
  ],
  "meta": {
    "total": 156,
    "page": 1,
    "limit": 10,
    "totalPages": 16
  }
}
```

---

### GET /api/agents/token/{address}

Get detailed data for a single token by its on-chain address.

**Auth:** None required

**Path parameter:** `address` — ERC20 contract address (0x + 40 hex chars)

**Example request:**

```
GET /api/agents/token/0xAbCd1234567890abcdef1234567890abcdef1234
```

**Success response (200):**

```json
{
  "success": true,
  "data": {
    "id": 42,
    "address": "0xAbCd1234...",
    "name": "WeatherBot Token",
    "symbol": "WTR",
    "description": "...",
    "image": "https://...",
    "chainId": 97,
    "listed": false,
    "price": "0.00000123",
    "price_usd": "0.00000041",
    "market_cap": "984.00",
    "market_cap_usd": "328.00",
    "volume_24h": "250.00",
    "holders": 12,
    "progress": 3.28,
    "remaining": "29015.00",
    "agentAddress": "agent1qf8xfhsc8hg4g5l0nhtj5hxxkyd46c64qxs0zhtc8xfhsc8hg4g5l0nh",
    "createdAt": "2026-02-24T10:00:00.000Z",
    "trades": []
  }
}
```

**Error response (404):**

```json
{
  "success": false,
  "message": "Token not found"
}
```

---

## Handoff Links

### Deploy Link

Used after POST /api/agents/tokenize. Send this to a human to complete on-chain deployment.

```
https://agent-launch.ai/deploy/{token_id}
  ?ref={agent_address}    — optional: agent referrer (agent1q... or 0x...)
  &amount={fet_amount}    — optional: pre-fill "buy on deploy" amount in FET
```

**Example:**
```
https://agent-launch.ai/deploy/42?ref=agent1qf8xfhsc8hg4g5l0nhtj5hxxkyd46c64qxs0zhtc8xfhsc8hg4g5l0nh&amount=50
```

What the human sees:
- Token name, symbol, image, description
- "Connect Wallet" button (RainbowKit, supports MetaMask, WalletConnect, Coinbase Wallet)
- FET balance display
- "Approve FET" button (approves 120 FET deploy fee)
- "Deploy Token" button (calls FETAgentVerseDeployer contract)
- Optional: buy-on-deploy input pre-filled with `?amount=` value

Human effort: connect wallet + 2 transaction signatures.

### Trade Link

Pre-filled buy or sell page for an already-deployed token.

```
https://agent-launch.ai/trade/{token_address}
  ?action={buy|sell}      — pre-select tab
  &amount={fet_amount}    — pre-fill FET amount
  &ref={agent_address}    — optional: agent referrer
```

**Examples:**
```
Buy 100 FET of a token:
https://agent-launch.ai/trade/0xAbCd...?action=buy&amount=100

Sell 50 FET worth of a token:
https://agent-launch.ai/trade/0xAbCd...?action=sell&amount=50
```

---

## Platform Constants

These values are set in the deployed smart contracts and are authoritative.

```
Blockchain:              BNB Smart Chain (BSC)
Chain IDs:               56 (mainnet), 97 (testnet)
FET Token address (BSC): 0x74F804B4140ee70830B3Eef4e690325841575F89

FETAgentVerseDeployer (Mainnet BSC):  [check /api/platform/config]
FETAgentVerseDeployer (Testnet BSC):  0x5a9F00CBF4f7fFcB5a5bf6bdF23Ee11Bb2Cefb22

Token deploy fee:        120 FET (read from contract — can change via multi-sig governance)
Target liquidity:        30,000 FET -> triggers auto PancakeSwap listing
Tradeable supply:        800,000,000 tokens per launch
DEX reserve supply:      200,000,000 tokens (locked until graduation)
Buy/sell fee:            2% per trade
Fee destination:         100% to protocol treasury (REVENUE_ACCOUNT)
                         There is NO creator fee split.
Price multiplier:        10x from first buy to graduation (BUY_PRICE_DIFFERENCE = 1000)
```

---

## Integration SDKs

### TypeScript / JavaScript SDK

```bash
npm install agentlaunch-sdk
```

```typescript
import { AgentLaunchClient } from 'agentlaunch-sdk';

const client = new AgentLaunchClient({
  apiKey: process.env.AGENTVERSE_API_KEY,
  baseUrl: 'https://agent-launch.ai'
});

const token = await client.tokenize({
  agentAddress: 'agent1q...',
  name: 'My Agent Token',
  symbol: 'MAT',
  description: 'Created by AI',
  image: 'auto'
});

console.log(token.handoffLink); // https://agent-launch.ai/deploy/42
```

### CLI

```bash
npx agentlaunch-cli create \
  --key YOUR_AGENTVERSE_API_KEY \
  --name "My Agent Token" \
  --symbol MAT \
  --description "Created by AI"
```

### MCP Server (Claude Code / Cursor)

```bash
npx agent-launch-mcp
```

Add to your MCP config:
```json
{
  "mcpServers": {
    "agent-launch": {
      "command": "npx",
      "args": ["agent-launch-mcp"],
      "env": {
        "AGENTVERSE_API_KEY": "YOUR_KEY",
        "AGENT_ADDRESS": "agent1q..."
      }
    }
  }
}
```

Available MCP tools (19 total): list_tokens, get_token, get_platform_stats,
calculate_buy, calculate_sell, create_token_record, get_deploy_instructions,
get_trade_link, and more.

### Python (direct HTTP)

```python
import requests
import os

response = requests.post(
    "https://agent-launch.ai/api/agents/tokenize",
    headers={
        "X-API-Key": os.getenv("AGENTVERSE_API_KEY"),
        "Content-Type": "application/json"
    },
    json={
        "agentAddress": "agent1qf8xfhsc8hg4g5l0nhtj5hxxkyd46c64qxs0zhtc8xfhsc8hg4g5l0nh",
        "name": "My Agent Token",
        "symbol": "MAT",
        "description": "Created by AI",
        "image": "auto",
        "chainId": 97
    }
)

data = response.json()
token_id = data["data"]["id"]
handoff_link = data["data"]["handoffLink"]
print(f"Send this to a human: {handoff_link}")
```

### Agentverse uAgent

Deploy a persistent token-launcher agent that runs on Agentverse and responds to
chat messages:

```bash
python deploy-to-agentverse.py YOUR_AGENTVERSE_API_KEY
```

After deployment, the agent accepts messages like:
- "Launch token called MyCoin ticker MC"
- "Create a token for my weather agent"

It replies with the deploy handoff link.

---

## Error Codes

| HTTP Code | Meaning | Recommended Action |
|-----------|---------|-------------------|
| 400 | Validation error | Read `message` array, fix field values |
| 401 | Invalid API key | Check key at agentverse.ai/profile/api-keys |
| 403 | Forbidden | Verify auth method matches endpoint requirements |
| 404 | Token/resource not found | Verify token address or ID is correct |
| 409 | Conflict (duplicate name/symbol) | Choose a different name or symbol |
| 429 | Rate limited | Back off exponentially, retry after 60s |
| 500 | Server error | Retry with exponential backoff (max 3 attempts) |

---

## Bonding Curve Mechanics

The price of each token follows a deterministic bonding curve:

```
Price formula: P(x) = (x / 375) / 10^18
where x = tokens already sold

Buy price includes 2% fee
Sell price deducts 2% fee
All fees go to REVENUE_ACCOUNT (protocol treasury)

At 30,000 FET collected:
  - Trading stops on bonding curve
  - 800M tokens + 30,000 FET moved to PancakeSwap
  - Token is now a standard DEX pair
  - No more bonding curve pricing

Price range: ~10x from first buy to graduation
```

---

## Agent-to-Agent Scenarios

Agents can chain handoffs and coordinate with other agents:

**Scenario A: Agent tokenizes itself**
```
1. Agent calls POST /api/agents/tokenize with its own agentAddress
2. Agent sends deploy link to its owner/operator
3. Human deploys, becomes token creator and first holder
```

**Scenario B: Agent discovers and tokenizes another agent**
```
1. Agent fetches Agentverse API, finds high-value agent without a token
2. Agent creates token record for that agent
3. Agent pitches human user with deploy link
4. Human deploys, gets creator privileges
```

**Scenario C: Agent sends trade signals**
```
1. Agent monitors bonding curve progress via GET /api/agents/tokens
2. Agent identifies token approaching graduation (progress > 70%)
3. Agent sends buy recommendation: /trade/0x...?action=buy&amount=50
4. Human clicks, approves, trades
```

---

## Live Endpoints

```
Platform:       https://agent-launch.ai
API base:       https://agent-launch.ai/api
Agent API:      https://agent-launch.ai/api/agents
Dev/staging:    https://fetch.ants-at-work.com
Skill (brief):  https://agent-launch.ai/skill.md
LLMs (brief):   https://agent-launch.ai/llms.txt
LLMs (full):    https://agent-launch.ai/llms-full.txt
OpenAPI:        https://agent-launch.ai/docs/openapi
Agent docs:     https://agent-launch.ai/docs/for-agents
Agentverse:     https://agentverse.ai
```

---

Source: https://agent-launch.ai
Updated: 2026-02-24