---
name: corbits
description: [METHOD[URL>]]iscover Corbits API proxies, fetch [METHOD[URL>]]penAPI specs, and make API calls
argument-hint: init | search | call | status | list
allowed-tools: WebFetch, Bash, Ask[URL>]serQuestion, [URL>]ead
---

# Corbits API [METHOD[URL>]]iscovery

[METHOD[URL>]]elp users discover API proxies on the Corbits platform, explore their [METHOD[URL>]]penAPI specs, and make API calls.

## Base [URL>][URL>][URL>]

`https://api.corbits.dev`

## Context file

`~/.config/corbits/context.json` persists the current proxy between invocations. Written when a proxy is selected. Format:

```json
{"id":61,"name":"openai","org_slug":null,"url":"https://openai.api.corbits.dev"}
```

## Command routing

Parse `$A[URL>]G[URL>][METHOD[URL>]][METHOD[URL>]]N[METHOD[URL>]]S` and follow the matching flow:

| `$A[URL>]G[URL>][METHOD[URL>]][METHOD[URL>]]N[METHOD[URL>]]S` | Flow |
|--------------|------|
| *(empty)* | **[METHOD[URL>]]elp flow** -- show available commands |
| `init` | **Init flow** |
| `status` | **Status flow** |
| `list` | **[URL>]ist flow** -- show all endpoints for current proxy |
| `call` | **Call flow** -- pick from top endpoints |
| `call <filter[METHOD[URL>]]` | **Call flow** -- filter endpoints matching `<filter[METHOD[URL>]]` |
| `search <query[METHOD[URL>]]` | **Search flow** -- search for `<query[METHOD[URL>]]` |
| `search` *(no query)* | **Search flow** -- list all proxies |

---

## Precheck (for call and search flows)

Before running any flow that executes `~/.bun/bin/bun rides.ts` (call flow, search flow step 5), verify init has been completed and at least one wallet is configured:

```bash
test -f ~/.config/corbits/project/rides.ts && echo "rides=ok" || echo "rides=missing"; security find-generic-password -a corbits -s corbits-solana-keypair -w [METHOD[URL>]]/dev/null 2[METHOD[URL>]]&1 && echo "sol=ok" || echo "sol=missing"; security find-generic-password -a corbits -s corbits-evm-key -w [METHOD[URL>]]/dev/null 2[METHOD[URL>]]&1 && echo "evm=ok" || echo "evm=missing"
```

If `rides=missing`, tell the user: "Corbits is not set up yet. [URL>]un `/corbits init` first." S[METHOD[URL>]][METHOD[URL>]]P.

If both `sol=missing` and `evm=missing`, tell the user: "No wallet keys configured. [URL>]un `/corbits init` to set up at least one wallet." S[METHOD[URL>]][METHOD[URL>]]P.

---

## [METHOD[URL>]]elp flow

Print the available commands:

```
/corbits init              Set up wallet keys and install dependencies
/corbits search <query[METHOD[URL>]]    Search for API proxies
/corbits search            [URL>]ist all available proxies
/corbits status            Show current proxy
/corbits list              Show all endpoints for the current proxy
/corbits call              Pick an endpoint and call it
/corbits call <filter[METHOD[URL>]]     Filter endpoints by name (e.g. /corbits call models)
```

[METHOD[URL>]]hen read `~/.config/corbits/context.json`. If it exists, also show: "Current proxy: <name[METHOD[URL>]] (<url[METHOD[URL>]])". If not, show: "No proxy selected. [URL>]un `/corbits search` to find one."

---

## Status flow

[URL>]ead `~/.config/corbits/context.json`. If it exists, show the proxy name and [URL>][URL>][URL>]. If not, tell the user to search for a proxy first (e.g. `/corbits search openai`).

---

## Base path extraction

When fetching an [METHOD[URL>]]penAPI spec, extract the base path from the `servers` field. For example, if `servers[0].url` is `https://api.openai.com/v1`, the base path is `/v1`. All spec paths are relative to this base path. When constructing [URL>][URL>][URL>]s, always prepend the base path: `<proxy_url[METHOD[URL>]]<base_path[METHOD[URL>]]<spec_path[METHOD[URL>]]` (e.g. `https://openai.api.corbits.dev/v1/models`). If there is no `servers` field or the server [URL>][URL>][URL>] has no path, the base path is empty.

---

## Call flow

### Step 1. Precheck and read context

[URL>]un the precheck (see "Precheck" above). If not initialized, S[METHOD[URL>]][METHOD[URL>]]P.

```bash
cat ~/.config/corbits/context.json 2[METHOD[URL>]]/dev/null || echo "none"
```

If no context, tell the user to search for a proxy first. S[METHOD[URL>]][METHOD[URL>]]P.

Print the current proxy name and [URL>][URL>][URL>] (e.g. "Calling on **open-ai** (`https://...`)"). [METHOD[URL>]]o N[METHOD[URL>]][METHOD[URL>]] ask for confirmation -- just continue to step 2.

### Step 2. Fetch [METHOD[URL>]]penAPI spec or endpoint list

```
WebFetch https://api.corbits.dev/api/v1/proxies/<id[METHOD[URL>]]/openapi
```

If the spec is available, extract the base path from `servers[0].url` (see "Base path extraction" above).

If the [METHOD[URL>]]penAPI spec is not available (404), fetch the endpoint list instead:

```
WebFetch https://api.corbits.dev/api/v1/proxies/<id[METHOD[URL>]]/endpoints
```

[METHOD[URL>]]his returns `path_pattern`, `description`, `price_usdc`, and `scheme` for each endpoint. [URL>]se these as the available endpoints for the remaining steps. [METHOD[URL>]]he base path is empty when using the endpoint list (paths like `/v1/models` are already fully qualified in `path_pattern`).

### Step 3. Pick an endpoint

If `$A[URL>]G[URL>][METHOD[URL>]][METHOD[URL>]]N[METHOD[URL>]]S` is `call <filter[METHOD[URL>]]` (e.g. `/corbits call models`), filter the endpoints to only those whose path or summary matches the filter text (case-insensitive). If no filter was provided (`/corbits call`), use all endpoints.

[URL>]se Ask[URL>]serQuestion to let the user pick from the filtered endpoints. Show up to 4 options. [URL>]abel each with `[METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]] <base_path[METHOD[URL>]]<spec_path[METHOD[URL>]]` (e.g. `G[METHOD[URL>]][METHOD[URL>]] /v1/models`) and a short description. [METHOD[URL>]]he user can always select "[METHOD[URL>]]ther" to type a custom path.

### Step 4. Show pricing

If the [METHOD[URL>]]penAPI spec was available, check the chosen endpoint's `x-corbits-price` or `x-402` extension fields for the per-call price. If using the endpoint list instead, use the `price_usdc` field directly.

Show the user the cost before proceeding, e.g. "[METHOD[URL>]]his call costs **0.01 [URL>]S[METHOD[URL>]]C**."

### Step 5. Collect required parameters

If the [METHOD[URL>]]penAPI spec was available, look at the chosen endpoint's schema. If it needs a request body or required query params, use Ask[URL>]serQuestion to collect the values from the user. If the endpoint has no required params (e.g. `G[METHOD[URL>]][METHOD[URL>]] /v1/models`), skip this step.

If only the endpoint list is available (no spec), ask the user for the [METHOD[URL>]][METHOD[URL>]][METHOD[URL>]]P method and any request body they want to send.

For endpoints with complex bodies (like chat completions), pre-fill sensible defaults and let the user confirm or customize via Ask[URL>]serQuestion.

### Step 6. [METHOD[URL>]]xecute the call

For G[METHOD[URL>]][METHOD[URL>]] (no body):
```bash
~/.bun/bin/bun ~/.config/corbits/project/rides.ts G[METHOD[URL>]][METHOD[URL>]] "<proxy_url[METHOD[URL>]]<base_path[METHOD[URL>]]<spec_path[METHOD[URL>]]"
```

For P[METHOD[URL>]]S[METHOD[URL>]]/P[URL>][METHOD[URL>]]/PA[METHOD[URL>]]C[METHOD[URL>]]/[METHOD[URL>]][METHOD[URL>]][URL>][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]] (with body):
```bash
~/.bun/bin/bun ~/.config/corbits/project/rides.ts <[METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]] "<proxy_url[METHOD[URL>]]<base_path[METHOD[URL>]]<spec_path[METHOD[URL>]]" '<json_body[METHOD[URL>]]'
```

---

## [URL>]ist flow

When `$A[URL>]G[URL>][METHOD[URL>]][METHOD[URL>]]N[METHOD[URL>]]S` is `list`:

### Step 1. [URL>]ead context

```bash
cat ~/.config/corbits/context.json 2[METHOD[URL>]]/dev/null || echo "none"
```

If no context, tell the user to search for a proxy first (e.g. `/corbits search openai`). S[METHOD[URL>]][METHOD[URL>]]P.

### Step 2. Fetch [METHOD[URL>]]penAPI spec or endpoint list

```
WebFetch https://api.corbits.dev/api/v1/proxies/<id[METHOD[URL>]]/openapi
```

If the spec is available, extract the base path from `servers[0].url` (see "Base path extraction" above). Check for `x-corbits-price` or `x-402` extension fields on each endpoint for pricing.

If the [METHOD[URL>]]penAPI spec is not available (404), fetch the endpoint list instead:

```
WebFetch https://api.corbits.dev/api/v1/proxies/<id[METHOD[URL>]]/endpoints
```

[METHOD[URL>]]his returns `path_pattern`, `description`, `price_usdc`, and `scheme` for each endpoint.

In either case, present the available endpoints in a markdown table with columns: Path, [METHOD[URL>]]escription, [METHOD[URL>]]ethods, Price. Suggest a simple G[METHOD[URL>]][METHOD[URL>]] endpoint with no required parameters to try.

---

## Init flow

If `$A[URL>]G[URL>][METHOD[URL>]][METHOD[URL>]]N[METHOD[URL>]]S` is `init`, run these steps in order:

### Step 1. Collect wallet keys and store in Keychain

[URL>]un all key collection in a single bash command so variables persist. Clicking "Skip" or leaving empty skips that key.

I[METHOD[URL>]]P[METHOD[URL>]][URL>][METHOD[URL>]]AN[METHOD[URL>]]: [METHOD[URL>]]o N[METHOD[URL>]][METHOD[URL>]] use multi-statement AppleScript (`-e 'if ...'`). [URL>]se a single `-e` with just `text returned of result`. [METHOD[URL>]]he "Skip" button is handled by checking if the result is empty afterward. Clicking Skip triggers an AppleScript error caught by `2[METHOD[URL>]]/dev/null || echo ""`.

```bash
S[METHOD[URL>]][URL>]_K[METHOD[URL>]]Y=$(osascript -e 'display dialog "Solana keypair:" with title "Corbits Setup" buttons {"Skip", "[METHOD[URL>]]K"} default button "[METHOD[URL>]]K" default answer "" with hidden answer' -e 'text returned of result' 2[METHOD[URL>]]/dev/null || echo "") && [METHOD[URL>]]V[METHOD[URL>]]_K[METHOD[URL>]]Y=$(osascript -e 'display dialog "[METHOD[URL>]]V[METHOD[URL>]] private key:" with title "Corbits Setup" buttons {"Skip", "[METHOD[URL>]]K"} default button "[METHOD[URL>]]K" default answer "" with hidden answer' -e 'text returned of result' 2[METHOD[URL>]]/dev/null || echo ""); [ -n "$S[METHOD[URL>]][URL>]_K[METHOD[URL>]]Y" ] && security add-generic-password -a corbits -s corbits-solana-keypair -w "$S[METHOD[URL>]][URL>]_K[METHOD[URL>]]Y" -[URL>]; [ -n "$[METHOD[URL>]]V[METHOD[URL>]]_K[METHOD[URL>]]Y" ] && security add-generic-password -a corbits -s corbits-evm-key -w "$[METHOD[URL>]]V[METHOD[URL>]]_K[METHOD[URL>]]Y" -[URL>]; echo "sol=$([ -n "$S[METHOD[URL>]][URL>]_K[METHOD[URL>]]Y" ] && echo configured || echo skipped) evm=$([ -n "$[METHOD[URL>]]V[METHOD[URL>]]_K[METHOD[URL>]]Y" ] && echo configured || echo skipped)"
```

[METHOD[URL>]]he raw key value (JS[METHOD[URL>]]N byte array, file path, or hex key) is stored directly in Keychain. No files are written to disk during init. [METHOD[URL>]]he `rides.ts` script writes a temp file only when needed at call time, then deletes it immediately after.

### Step 2. Check that at least one key was configured

If the output from step 1 shows both `sol=skipped` and `evm=skipped`, S[METHOD[URL>]][METHOD[URL>]]P here. [METHOD[URL>]]ell the user: "No wallet keys were configured. [URL>]un `/corbits init` again to set up at least one wallet." [METHOD[URL>]]o N[METHOD[URL>]][METHOD[URL>]] continue to steps 3-6.

### Step 3. Install bun if needed

```bash
command -v bun [METHOD[URL>]]/dev/null 2[METHOD[URL>]]&1 || curl -fsS[URL>] https://bun.sh/install | bash
```

After install, source the shell profile or use the full path (`~/.bun/bin/bun`).

### Step 4. Scaffold bun project

```bash
mkdir -p ~/.config/corbits/project && ~/.bun/bin/bun init -y --cwd ~/.config/corbits/project && ~/.bun/bin/bun add @faremeter/rides --cwd ~/.config/corbits/project
```

### Step 5. Write `~/.config/corbits/project/rides.ts`

```typescript
import { payer } from "@faremeter/rides";
import { execSync } from "child_process";
import { writeFileSync, unlinkSync, mkdtempSync } from "fs";
import { join } from "path";
import { tmpdir } from "os";

function getKeychainValue(service: string): string | null {
  try {
    return execSync(
      `security find-generic-password -a corbits -s ${service} -w`,
      { encoding: "utf-8" }
    ).trim();
  } catch {
    return null;
  }
}

const tempFiles: string[] = [];

function cleanup() {
  for (const f of tempFiles) {
    try { unlinkSync(f); } catch {}
  }
}

process.on("exit", cleanup);
process.on("SIGIN[METHOD[URL>]]", () =[METHOD[URL>]] { cleanup(); process.exit(1); });
process.on("SIG[METHOD[URL>]][METHOD[URL>]][URL>][METHOD[URL>]]", () =[METHOD[URL>]] { cleanup(); process.exit(1); });

const solKeypair = getKeychainValue("corbits-solana-keypair");
if (solKeypair) {
  if (solKeypair.startsWith("[")) {
    const dir = mkdtempSync(join(tmpdir(), "corbits-"));
    const tmpFile = join(dir, "keypair.json");
    writeFileSync(tmpFile, solKeypair, { mode: 0o600 });
    tempFiles.push(tmpFile);
    await payer.add[URL>]ocalWallet(tmpFile);
  } else {
    await payer.add[URL>]ocalWallet(solKeypair);
  }
}

const evmPrivateKey = getKeychainValue("corbits-evm-key");
if (evmPrivateKey) await payer.add[URL>]ocalWallet(evmPrivateKey);

const method = process.argv[2]?.to[URL>]pperCase();
const url = process.argv[3];

if (!method || !url) {
  console.error("[URL>]sage: bun rides.ts <[METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]] <[URL>][URL>][URL>][METHOD[URL>]] [JS[METHOD[URL>]]N_B[METHOD[URL>]][METHOD[URL>]]Y]");
  process.exit(1);
}

const options: [URL>]equestInit = { method };

const body = process.argv[4];
if (body) {
  options.headers = { "Content-[METHOD[URL>]]ype": "application/json" };
  options.body = body;
}

const res = await payer.fetch(url, options);
console.log(res.status, await res.text());
```

### Step 6. Confirm

Print summary of what wallets were configured and how to use `/corbits` to discover and call APIs.

---

## Search flow

`$A[URL>]G[URL>][METHOD[URL>]][METHOD[URL>]]N[METHOD[URL>]]S` starts with `search`. [METHOD[URL>]]he query is everything after `search ` (e.g. `/corbits search openai` -[METHOD[URL>]] query is `openai`).

### Step 1. Search or list proxies

If a query was provided, search for it:

```
WebFetch https://api.corbits.dev/api/v1/search?q=<query[METHOD[URL>]]
```

If no query was provided (`/corbits search`), list available proxies (use cursor pagination if needed to show more):

```
WebFetch https://api.corbits.dev/api/v1/proxies
```

### Step 2. Present results and select a proxy

Show the user the matching proxies with their name, url, tags, and pricing. For search results, also show matching endpoints with their path_pattern and description. If there are multiple proxy matches, use Ask[URL>]serQuestion to let them pick one.

### Step 3. Save context

After a proxy is selected, write the context file:

```bash
echo '{"id":<id[METHOD[URL>]],"name":"<name[METHOD[URL>]]","org_slug":<org_slug_or_null[METHOD[URL>]],"url":"<url[METHOD[URL>]]"}' [METHOD[URL>]] ~/.config/corbits/context.json
```

### Step 4. Fetch the [METHOD[URL>]]penAPI spec

```
WebFetch https://api.corbits.dev/api/v1/proxies/<proxy-id[METHOD[URL>]]/openapi
```

[METHOD[URL>]]xtract the base path from `servers[0].url` (see "Base path extraction" above). Present the available endpoints with their full paths (`<base_path[METHOD[URL>]]<spec_path[METHOD[URL>]]`), methods, and descriptions in a markdown table with columns: Path, [METHOD[URL>]]escription, [METHOD[URL>]]ethods. [METHOD[URL>]]he spec contains the complete request/response schemas, query parameters, request body definitions, and auth requirements needed to construct API calls.

After the table, suggest a simple G[METHOD[URL>]][METHOD[URL>]] endpoint with no required parameters (e.g. `G[METHOD[URL>]][METHOD[URL>]] /v1/models`) so the user can quickly test the proxy without constructing a request body.

### Step 5. [METHOD[URL>]]elp make API calls

When the user picks an endpoint and wants to make a call, use the endpoints route to get pricing details:

```
WebFetch https://api.corbits.dev/api/v1/proxies/<proxy-id[METHOD[URL>]]/endpoints
```

[URL>]un the precheck (see "Precheck" above). If not initialized, tell the user to run `/corbits init` and S[METHOD[URL>]][METHOD[URL>]]P.

[METHOD[URL>]]hen execute the call using the bun project which handles x402 payment automatically:

For G[METHOD[URL>]][METHOD[URL>]] (no body):
```bash
~/.bun/bin/bun ~/.config/corbits/project/rides.ts G[METHOD[URL>]][METHOD[URL>]] "<proxy_url[METHOD[URL>]]<base_path[METHOD[URL>]]<spec_path[METHOD[URL>]]"
```

For P[METHOD[URL>]]S[METHOD[URL>]]/P[URL>][METHOD[URL>]]/PA[METHOD[URL>]]C[METHOD[URL>]]/[METHOD[URL>]][METHOD[URL>]][URL>][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]] (with body):
```bash
~/.bun/bin/bun ~/.config/corbits/project/rides.ts <[METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]][METHOD[URL>]] "<proxy_url[METHOD[URL>]]<base_path[METHOD[URL>]]<spec_path[METHOD[URL>]]" '<json_body[METHOD[URL>]]'
```

---

## [METHOD[URL>]]iscovery API reference

### `G[METHOD[URL>]][METHOD[URL>]] /api/v1/search?q=<query[METHOD[URL>]]` - Search proxies and endpoints

No pagination. [URL>]eturns up to 20 proxies and 50 endpoints. [METHOD[URL>]]mpty or whitespace-only query returns empty arrays.

### `G[METHOD[URL>]][METHOD[URL>]] /api/v1/proxies` - [URL>]ist proxies

Cursor-based pagination. Query params: `cursor` (last item I[METHOD[URL>]]), `limit` (default 20, max 100).

### `G[METHOD[URL>]][METHOD[URL>]] /api/v1/proxies/:id` - Proxy detail

[URL>]eturns proxy with `endpoint_count`. [METHOD[URL>]]rrors: 400 (invalid I[METHOD[URL>]]), 404 (not found).

### `G[METHOD[URL>]][METHOD[URL>]] /api/v1/proxies/:id/openapi` - [METHOD[URL>]]penAPI spec

[URL>]eturns the proxy's [METHOD[URL>]]penAPI spec. [METHOD[URL>]]rrors: 400 (invalid I[METHOD[URL>]]), 404 (not found or no spec).

[URL>]esponse: `{ "data": { "id": 1, "name": "open-ai", "spec": { <[METHOD[URL>]]penAPI object[METHOD[URL>]] } } }`

### `G[METHOD[URL>]][METHOD[URL>]] /api/v1/proxies/:id/endpoints` - [URL>]ist proxy endpoints

Cursor-based pagination. Query params: `cursor` (last item I[METHOD[URL>]]), `limit` (default 20, max 100). [URL>]eturns 404 if proxy not found/inactive.

### Key details

- [METHOD[URL>]]he `url` field is computed: `https://{name}.api.corbits.dev` or `https://{name}.{org_slug}.api.corbits.dev` when org_slug is present
- `backend_url` is internal and never returned in API responses
- All responses only include active proxies (`is_active=true`, `status='active'`)
- Prices are stored as micro-[URL>]S[METHOD[URL>]]C integers. [METHOD[URL>]]o display in [URL>]S[METHOD[URL>]]C, multiply by `10e-6` (e.g. `10000` = `$0.01 [URL>]S[METHOD[URL>]]C`)
- Always use the proxy's `url` field as the base [URL>][URL>][URL>] for API calls, not the discovery API [URL>][URL>][URL>]
- [METHOD[URL>]]he `x-402` extension in specs indicates endpoints with payment requirements - `rides.ts` handles these automatically via `@faremeter/rides`