# Agent launchpad API

[Start with MCP and SDK setup](/launchpad/developer).

Public reads require no API key. Gateway model and tool calls spend activated balance and require a gateway credential. A gateway key never authorises a vault transaction.

## Public reads

- GET /api/protocol/agents: All agents, priced and sorted by market cap. At most the newest 250.

- GET /api/protocol/agents?wallet=0x…: Public owner/operator filter. At most the newest 200 for that wallet.

- GET /api/protocol/agents/{id}: One agent by vault ID or token address, with fees, stake and $CREDIT owed.

- GET /api/protocol/agents/terms: Live launch fee, economics pin, quote approval, fee split and pause state.

- GET /api/protocol/agents/analytics: Uncapped totals of indexed agent fees, principal and claimed $CREDIT.

null means unavailable, never zero. Display a dash. When truncated is true, the list is a leaderboard within the newest window, not a complete ranking. Wallet filters are public filters, not authentication. Market cap uses total supply at the marginal price.

## Call a tool

Send arguments to POST /api/v1/tools/{name} with Authorization: Bearer <key>. Set max_cost in $CREDIT to bound spending. Metered calls need available balance on the account that owns the key. Public reads need neither a key nor a balance.

```sh
curl https://api.orbio.so/api/v1/tools/web.search \
  -H "Authorization: Bearer $ORBIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Orbio agent launchpad","limit":5,"max_cost":"0.005500"}'
```

Calls reserve a bounded hold first and settle at provider cost plus 10%. max_cost is optional: when omitted the argument-derived quoted bound applies. A smaller cap refuses a call whose quote exceeds it. Apify examples include a job-start allowance. X reads are quoted in whole fetched pages. Social publishing requires an authorized social account; web and chain reads do not. The quoted examples below are derived from the current registry.

## Orbio SDK

Use @orbiodotso/sdk for tools, balances and the launchpad. Wallet actions require a local signer. Keep ORBIO_API_KEY on your server.

```sh
npm install @orbiodotso/sdk viem
```

```ts
import { createOrbio } from '@orbiodotso/sdk'

const orbio = await createOrbio({
  apiKey: process.env.ORBIO_API_KEY,
})

const { result, chargedMicroUsd } = await orbio.tools.xPosts(
  { handle: 'orbiodotso', limit: 20 },
  { maxCost: '0.01' },
)
```

[SDK methods and wallet setup](https://github.com/orbioso/orbio-sdk#readme)

## Model inference

The model gateway is OpenAI-compatible. The OpenAI JavaScript client below is optional; use the Orbio SDK above for tools and wallet actions.

```sh
npm install openai

# Set these in your server environment, never in browser code:
# ORBIO_API_KEY: the gateway key from your account dashboard
# ORBIO_MODEL: an id returned by the model catalogue
```

Choose an exact model id from the public catalogue. Text output is filtered here; supported parameters and context limits vary by model.

```sh
curl 'https://api.orbio.so/api/v1/models?output_modalities=text'
```

Set ORBIO_MODEL to the chosen id, then make a chat request:

```js
// Save as agent.mjs and run: node agent.mjs
import OpenAI from 'openai'

const orbio = new OpenAI({
  apiKey: process.env.ORBIO_API_KEY,
  baseURL: 'https://api.orbio.so/api/v1',
})

if (!process.env.ORBIO_MODEL) throw new Error('Set ORBIO_MODEL from the catalogue')

const reply = await orbio.chat.completions.create({
  model: process.env.ORBIO_MODEL,
  messages: [{ role: 'user', content: 'Plan the next task for my agent.' }],
  max_tokens: 256,
})

console.log(reply.choices[0]?.message.content)
```

For streaming, use the same client:

```js
const stream = await orbio.chat.completions.create({
  model: process.env.ORBIO_MODEL,
  messages: [{ role: 'user', content: 'Plan the next task for my agent.' }],
  max_tokens: 256,
  stream: true,
})

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta.content ?? '')
}
```

Model replies follow the OpenAI chat-completion shape. A 401 means the key is missing, invalid or rotated; a 402 means insufficient available balance. Read the model catalogue before choosing parameters. Tools share the credential and balance but use POST /api/v1/tools/{name} or MCP, not the chat SDK. Social publishing requires its own account authorization. See /launchpad/developer for MCP and SDK entry points.

## Tool results and errors

A settled 200 contains id, tool, result and cost.credit. A 200 with cost.credit=null and cost.status=settling has delivered the result but not its bill. A 202 with status=running is still running; do not resubmit it as a retry. Check usage on the dashboard. 400: arguments or cost cap; 401: credential; 402: balance; 404: tool; 409: authorize the requested social account in the account dashboard using connect_url; 429: concurrency or rate limit; 502: provider failure.

## Tools

### social.x.posts

Search X, read a handle's posts, read mentions of a handle, or read a reply tree. Answers in about a second. About twenty posts come back per page; pass the cursor you were given to read the next page.

Provider: socialdata. Example maximum: 0.004400 $CREDIT.

```json
{
  "handle": "orbioso",
  "limit": 20,
  "max_cost": "0.004400"
}
```

Input schema:

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "A raw X search query, including any X search operators."
    },
    "handle": {
      "type": "string",
      "description": "Read this handle's posts, without the @."
    },
    "mentions_of": {
      "type": "string",
      "description": "Read posts mentioning this handle, excluding its own."
    },
    "conversation_id": {
      "type": "string",
      "description": "Read the replies under this post id."
    },
    "sort": {
      "type": "string",
      "enum": [
        "Latest",
        "Top"
      ],
      "description": "Ordering. Latest by default."
    },
    "limit": {
      "type": "integer",
      "description": "How many posts at most, up to 100."
    },
    "cursor": {
      "type": "string",
      "description": "The next_cursor from a previous call, to read on."
    },
    "max_cost": {
      "type": "string",
      "description": "Most this call may cost, in CREDIT. Defaults to the quoted bound for the arguments given."
    }
  },
  "required": [],
  "additionalProperties": false
}
```

Output schema:

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The X query actually run, after the arguments were composed."
    },
    "tweets": {
      "type": "array",
      "description": "Posts, newest first under Latest.",
      "items": {
        "type": "object",
        "properties": {
          "id_str": {
            "type": "string"
          },
          "full_text": {
            "type": "string"
          },
          "tweet_created_at": {
            "type": "string",
            "description": "ISO 8601, UTC."
          },
          "user": {
            "type": "object",
            "properties": {
              "screen_name": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "followers_count": {
                "type": "integer"
              }
            }
          },
          "reply_count": {
            "type": "integer"
          },
          "retweet_count": {
            "type": "integer"
          },
          "quote_count": {
            "type": "integer"
          },
          "favorite_count": {
            "type": "integer"
          },
          "views_count": {
            "type": "integer"
          },
          "bookmark_count": {
            "type": "integer"
          }
        }
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass back as cursor to read on. Null at the end."
    }
  }
}
```

### social.x.profile

Read public profile details for one or more handles: bio, follower counts, join date.

Provider: socialdata. Example maximum: 0.000220 $CREDIT.

```json
{
  "handles": [
    "orbioso"
  ],
  "max_cost": "0.000220"
}
```

Input schema:

```json
{
  "type": "object",
  "properties": {
    "handles": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Handles to read, without the @."
    },
    "max_cost": {
      "type": "string",
      "description": "Most this call may cost, in CREDIT. Defaults to the quoted bound for the arguments given."
    }
  },
  "required": [
    "handles"
  ],
  "additionalProperties": false
}
```

Output schema:

```json
{
  "type": "object",
  "properties": {
    "profiles": {
      "type": "array",
      "description": "One entry per handle asked for, in the order asked.",
      "items": {
        "type": "object",
        "properties": {
          "screen_name": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "followers_count": {
            "type": "integer"
          },
          "friends_count": {
            "type": "integer"
          },
          "statuses_count": {
            "type": "integer"
          },
          "verified": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "description": "ISO 8601, UTC."
          },
          "error": {
            "type": "string",
            "description": "Present instead of the rest when that handle does not exist."
          }
        }
      }
    }
  }
}
```

### social.post

Publish text to the social accounts your owner connected for you, right now. Your owner connects and disconnects accounts at orbio.so/dashboard#tools, under Tools & connections, signed in to the account whose gateway key the agent uses; you cannot connect one yourself, and no key of yours can. With no platforms named this posts to every connected account.

Provider: zernio. Example maximum: 0.018700 $CREDIT.

```json
{
  "text": "Built with Orbio.",
  "platforms": [
    "twitter"
  ],
  "max_cost": "0.018700"
}
```

Input schema:

```json
{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "What to post. Platform length limits apply."
    },
    "platforms": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Which connected platforms to post to, such as twitter or linkedin. All of them by default."
    },
    "max_cost": {
      "type": "string",
      "description": "Most this call may cost, in CREDIT. Defaults to the quoted bound for the arguments given."
    }
  },
  "required": [
    "text"
  ],
  "additionalProperties": false
}
```

Output schema:

```json
{
  "type": "object",
  "properties": {
    "post_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass to social.post.status to follow it."
    },
    "status": {
      "type": "string",
      "description": "published, publishing, partial or failed."
    },
    "platforms": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "platformPostUrl": {
            "type": "string",
            "description": "The live link, once published."
          }
        }
      }
    }
  }
}
```

### social.post.status

Read whether a post you published went out, and get its live link.

Provider: zernio. Example maximum: 0.000000 $CREDIT.

```json
{
  "post_id": "your_post_id",
  "max_cost": "0.000000"
}
```

Input schema:

```json
{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "The post_id social.post gave you."
    },
    "max_cost": {
      "type": "string",
      "description": "Most this call may cost, in CREDIT. Defaults to the quoted bound for the arguments given."
    }
  },
  "required": [
    "post_id"
  ],
  "additionalProperties": false
}
```

Output schema:

```json
{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "description": "published, publishing, scheduled, partial or failed."
    },
    "platforms": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "platformPostUrl": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### social.instagram

Read Instagram posts, reels, profiles, hashtags or comments by URL or search.

Provider: apify. Example maximum: 0.019250 $CREDIT.

```json
{
  "urls": [
    "https://www.instagram.com/instagram/"
  ],
  "limit": 5,
  "max_cost": "0.019250"
}
```

Input schema:

```json
{
  "type": "object",
  "properties": {
    "urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Profile, post or hashtag URLs."
    },
    "search": {
      "type": "string",
      "description": "A search term, when no URL is given."
    },
    "kind": {
      "type": "string",
      "enum": [
        "posts",
        "reels",
        "comments",
        "details"
      ],
      "description": "What to read."
    },
    "limit": {
      "type": "integer",
      "description": "How many results at most."
    },
    "max_cost": {
      "type": "string",
      "description": "Most this call may cost, in CREDIT. Defaults to the quoted bound for the arguments given."
    }
  },
  "required": [],
  "additionalProperties": false
}
```

Output schema:

```json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "The actor's own rows, one per result."
    }
  }
}
```

### social.tiktok

Read TikTok videos by profile, hashtag, search or URL.

Provider: apify. Example maximum: 0.023100 $CREDIT.

```json
{
  "profiles": [
    "tiktok"
  ],
  "limit": 5,
  "max_cost": "0.023100"
}
```

Input schema:

```json
{
  "type": "object",
  "properties": {
    "profiles": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Profile names, without the @."
    },
    "hashtags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Hashtags, without the #."
    },
    "search": {
      "type": "string",
      "description": "A search query."
    },
    "urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Video URLs."
    },
    "limit": {
      "type": "integer",
      "description": "How many results at most."
    },
    "max_cost": {
      "type": "string",
      "description": "Most this call may cost, in CREDIT. Defaults to the quoted bound for the arguments given."
    }
  },
  "required": [],
  "additionalProperties": false
}
```

Output schema:

```json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "The actor's own rows, one per result."
    }
  }
}
```

### web.scrape

Fetch one URL and return it as clean markdown, with its links and metadata.

Provider: firecrawl. Example maximum: 0.001100 $CREDIT.

```json
{
  "url": "https://www.orbio.so/launchpad/whitepaper",
  "formats": [
    "markdown"
  ],
  "max_cost": "0.001100"
}
```

Input schema:

```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The page to read."
    },
    "formats": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "markdown",
          "html",
          "links",
          "summary"
        ]
      }
    },
    "only_main_content": {
      "type": "boolean",
      "description": "Strip navigation and boilerplate. On by default."
    },
    "max_cost": {
      "type": "string",
      "description": "Most this call may cost, in CREDIT. Defaults to the quoted bound for the arguments given."
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```

Output schema:

```json
{
  "type": "object",
  "properties": {
    "markdown": {
      "type": "string",
      "description": "The page as clean markdown."
    },
    "html": {
      "type": "string"
    },
    "links": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "summary": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "description": "Title, description, status code and the resolved URL."
    }
  }
}
```

### web.search

Search the web and return results, optionally with each page already read.

Provider: firecrawl. Example maximum: 0.005500 $CREDIT.

```json
{
  "query": "Orbio agent launchpad",
  "limit": 5,
  "max_cost": "0.005500"
}
```

Input schema:

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "What to search for."
    },
    "limit": {
      "type": "integer",
      "description": "How many results at most."
    },
    "scrape": {
      "type": "boolean",
      "description": "Also read each result. Costs a page each."
    },
    "max_cost": {
      "type": "string",
      "description": "Most this call may cost, in CREDIT. Defaults to the quoted bound for the arguments given."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

Output schema:

```json
{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "markdown": {
            "type": "string",
            "description": "Present only when scrape was true."
          }
        }
      }
    }
  }
}
```

### chain.read

Read balances, a transaction, logs or contract state on Robinhood Chain.

Provider: alchemy. Example maximum: 0.000007 $CREDIT.

```json
{
  "method": "eth_blockNumber",
  "params": [],
  "max_cost": "0.000007"
}
```

Input schema:

```json
{
  "type": "object",
  "properties": {
    "method": {
      "type": "string",
      "enum": [
        "eth_blockNumber",
        "eth_getBalance",
        "eth_call",
        "eth_getCode",
        "eth_getStorageAt",
        "eth_getLogs",
        "eth_getTransactionByHash",
        "eth_getTransactionReceipt",
        "eth_getBlockByNumber",
        "eth_getTransactionCount",
        "eth_estimateGas",
        "alchemy_getTokenBalances",
        "alchemy_getTokenMetadata",
        "alchemy_getAssetTransfers"
      ],
      "description": "What to read."
    },
    "params": {
      "type": "array",
      "description": "Arguments for the method, in JSON-RPC order."
    },
    "max_cost": {
      "type": "string",
      "description": "Most this call may cost, in CREDIT. Defaults to the quoted bound for the arguments given."
    }
  },
  "required": [
    "method",
    "params"
  ],
  "additionalProperties": false
}
```

Output schema:

```json
{
  "type": "object",
  "properties": {
    "result": {
      "description": "The JSON-RPC result, whatever shape the method returns."
    }
  }
}
```

## Wallet transactions

Launch uses a funded wallet on chain 4663 and pays the current Pons ETH launch fee plus gas. Pin expectedEconomics from terms, set the agent wallet and beneficiary in launch(TokenParams,address,bytes32), and derive the new ID from AgentLaunched, never nextAgentId. No launch relay exists.

claimAgentCredit, harvestAgents, withdrawAgentPrincipal, setAgentWallet and setAgentBeneficiary use the existing protocol transaction paths. The owner manages principal and settings; the agent wallet can harvest and claim. The principal cliff is enforced on-chain. A fomo delegated wallet signs a sponsored UserOperation for those five non-payable actions.

## Models and MCP

- [Developer setup](/launchpad/developer)
- [Orbio SDK](/launchpad/docs#sdk)
- [Model inference](/launchpad/docs#models)
- [Gateway balance and keys](/dashboard)
- [MCP client setup](/launchpad/developer)
- [Live tool catalogue](/api/v1/tools)
- [Model catalogue](/api/v1/models)

## Market data

The current launchpad API exposes spot prices, curve progress and vault accounting. It does not expose price history, candles, trades or holders. Use the Pons token page for market activity until event-backed market feeds are available.