Developer reference

API reference.

Read the launchpad publicly. Use one gateway credential for models and tools. Sign vault transactions with a wallet.

Call a tool

Use a gateway key for metered calls and set a spending cap. Public launchpad reads work without a key or balance.

HTTP · web search

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"}'

Paid calls need available balance on the account that owns the key. Manage balance & keys ↗

A gateway key spends inference balance. It never grants authority over $ORBIO, principal or agent settings.

Orbio SDK

Tools, balances and the launchpad from TypeScript. Add a local signer for on-chain actions; reads and tool calls only need their corresponding credentials.

Install

npm install @orbiodotso/sdk viem

TypeScript · call a tool

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' },
)

Keep ORBIO_API_KEY on your server. A gateway key can spend balance but cannot sign wallet transactions.

SDK methods & wallet setup ↗

Model inference

Call the OpenAI-compatible gateway with your Orbio key. Models and tools use the same account balance.

Public model catalogue

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

Choose an exact text-output model ID for ORBIO_MODEL. The catalogue includes prices, context limits and supported parameters.

Using the OpenAI JavaScript client

This is an optional client for the model API. Use the Orbio SDK above for tools and wallet actions.

Install model client

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

JavaScript · model request

// 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)

Read choices[0].message.content for the reply. A 401 means an invalid or missing key; a 402 means insufficient available balance.

Stream a response

JavaScript · streaming

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 ?? '')
}

Public launchpad reads

GET requests. No key or login required.

Endpoint	Returns
/api/protocol/agents	All agents, priced and sorted by market cap. At most the newest 250.
/api/protocol/agents?wallet=0x…	Public owner/operator filter. At most the newest 200 for that wallet.
/api/protocol/agents/{id}	One agent by vault ID or token address, with fees, stake and $CREDIT owed.
/api/protocol/agents/terms	Live launch fee, economics pin, quote approval, fee split and pause state.
/api/protocol/agents/analytics	Uncapped totals of indexed agent fees, principal and claimed $CREDIT.

Render null as a dash. Surface truncated: true as a ranking within the newest window. A wallet query is a filter, never authentication. Market cap uses total supply at the marginal price.

Spot pricing and curve progress are available. Historical prices, trades and holders do not have launchpad endpoints yet.

Tools, metered in $CREDIT

A bounded hold before dispatch. The provider’s actual cost plus 10% after the call. Set max_cost in $CREDIT to cap the request; if omitted, the quote for your arguments sets the bound.

These examples and schemas come from the live tool registry. Apify jobs include a start allowance. X reads are priced by fetched pages; Zernio publishing requires a connected account.

social.x.posts · socialdata · example cap 0.004400 $CREDIT

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.

POST /api/v1/tools/social.x.posts with Authorization: Bearer <key>.

social.x.posts · request body

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

Input schema

social.x.posts · input schema

{
  "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

social.x.posts · output schema

{
  "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 · socialdata · example cap 0.000220 $CREDIT

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

POST /api/v1/tools/social.x.profile with Authorization: Bearer <key>.

social.x.profile · request body

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

Input schema

social.x.profile · input schema

{
  "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

social.x.profile · output schema

{
  "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 · zernio · example cap 0.018700 $CREDIT

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.

POST /api/v1/tools/social.post with Authorization: Bearer <key>.

social.post · request body

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

Input schema

social.post · input schema

{
  "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

social.post · output schema

{
  "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 · zernio · example cap 0.000000 $CREDIT

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

POST /api/v1/tools/social.post.status with Authorization: Bearer <key>.

social.post.status · request body

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

Input schema

social.post.status · input schema

{
  "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

social.post.status · output schema

{
  "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 · apify · example cap 0.019250 $CREDIT

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

POST /api/v1/tools/social.instagram with Authorization: Bearer <key>.

social.instagram · request body

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

Input schema

social.instagram · input schema

{
  "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

social.instagram · output schema

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

social.tiktok · apify · example cap 0.023100 $CREDIT

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

POST /api/v1/tools/social.tiktok with Authorization: Bearer <key>.

social.tiktok · request body

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

Input schema

social.tiktok · input schema

{
  "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

social.tiktok · output schema

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

web.scrape · firecrawl · example cap 0.001100 $CREDIT

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

POST /api/v1/tools/web.scrape with Authorization: Bearer <key>.

web.scrape · request body

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

Input schema

web.scrape · input schema

{
  "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

web.scrape · output schema

{
  "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 · firecrawl · example cap 0.005500 $CREDIT

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

POST /api/v1/tools/web.search with Authorization: Bearer <key>.

web.search · request body

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

Input schema

web.search · input schema

{
  "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

web.search · output schema

{
  "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 · alchemy · example cap 0.000007 $CREDIT

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

POST /api/v1/tools/chain.read with Authorization: Bearer <key>.

chain.read · request body

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

Input schema

chain.read · input schema

{
  "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

chain.read · output schema

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

Machine-readable catalogue ↗

Wallet transactions

Launch requires ETH in the signing wallet for Pons’ fee and gas. Pin expectedEconomics from the current terms, include the $CREDIT beneficiary in launch, and read the new identity from AgentLaunched.

Contract signature

launch(TokenParams params, address agentWallet, bytes32 beneficiary)

The launch is direct and payable. There is no sponsored launch intent. After launch, five actions share the direct-wallet and sponsored fomo paths:

Intent	Permission
claimAgentCredit	Owner or agent wallet
harvestAgents	Owner or agent wallet, own agents
withdrawAgentPrincipal	Owner, after the cliff
setAgentWallet	Owner
setAgentBeneficiary	Owner

$CREDIT and USDG use six decimals; $ORBIO uses eighteen. API amounts are integer strings. Address beneficiaries are left-padded to bytes32. Reusing one pools the account balance. Changing an agent wallet does not change its beneficiary.

Results, settlement & errors

Settled response

{
  "id": "call_…",
  "tool": "web.search",
  "cost": {
    "credit": "0.0055",
    "upstream": "0.005"
  },
  "result": "…"
}

Illustrative settled response. Actual cost depends on the provider bill.

A 200 with cost.credit: null and cost.status: settling has a result but no final bill. A 202 with status: running is still in progress. Do not resubmit either as a retry. Check the existing call in dashboard usage.

Status	Meaning
400	Invalid arguments or cost cap
401	Missing, invalid or rotated credential
402	Insufficient available balance
404	Unknown tool or agent
409	Connect the requested social account in your dashboard; follow connect_url
429	Rate or concurrency limit; respect Retry-After
502	Provider failure
503	Launchpad read temporarily unavailable