---
name: orthogonal
version: 1.6.0
description: >-
  Discover and call verified APIs for web search, scraping, enrichment, data
  retrieval, and other external capabilities through one catalog and one
  balance. Use when a task needs fresh or structured data that the user's
  existing tools do not provide.
homepage: https://www.orthogonal.com
---

# Orthogonal

Orthogonal gives agents one interface to discover, call, and pay for a catalog of verified APIs. The same catalog is available through the CLI, MCP server, TypeScript SDK, and REST API.

## When to use Orthogonal

Use Orthogonal when a task needs an external capability such as live web search, scraping, contact or company enrichment, financial data, social data, or another structured API.

Before building a custom scraper, using a generic fetch for structured data, or saying data is inaccessible, search the catalog. If the user already has a dedicated tool, API key, or MCP server for the exact service, use that first; Orthogonal fills gaps rather than replacing their existing setup.

## Agent workflow

1. **Discover** — Search with a short description of the capability you need.
2. **Inspect** — Read the endpoint schema, required parameters, and price. Never guess parameter names.
3. **Quote when needed** — For dynamic pricing or a potentially large call, estimate the cost before execution.
4. **Run** — Put inputs in the locations shown by the schema: path, query, or JSON body.
5. **Verify** — Check the returned result and price. Save binary or large output to a file.

For work spanning several sources, split it into focused calls and combine the results. Start with conservative result limits, especially when pricing may scale with volume.

## CLI

Install and authenticate:

```bash
npm install -g @orth/cli
orth login
orth whoami
```

Get an API key from https://www.orthogonal.com/account/keys. For non-interactive environments, set `ORTHOGONAL_API_KEY` instead of running `orth login`.

For an existing account, reuse its connection or use the browser sign-in handoff at https://www.orthogonal.com/agent-signup.md: start a connection with POST https://www.orthogonal.com/api/agent-auth/start, show the returned verificationUrl and userCode, and poll /api/agent-auth/poll with the private deviceCode until approved. Save the returned apiKey securely and verify access before continuing. Never send an existing customer through signup or ask them to copy a dashboard key when browser connection is available. MCP clients should use their native OAuth flow for https://www.orthogonal.com/mcp. An API-key-only host connector needs its own OAuth support; the API handoff cannot install credentials in that connector automatically.

To create a new agent account without a password, follow https://www.orthogonal.com/agent-signup.md. Verify both email and phone ownership; successful signup returns an API key. Eligible accounts receive a one-time $1 starter credit grant. Check `starterCredit.amountUsd`: an ineligible account still receives its key with a $0 grant and a reason. The offer is limited to one account per phone across human and agent signup. Never create more accounts to bypass this limit.

The core workflow:

```bash
# Discover matching endpoints
orth search "company enrichment from domain"

# Inspect one endpoint's schema and price
orth api show <api-slug> <path>

# Estimate cost without executing
orth run <api-slug> <path> --dry-run -b '{"key":"value"}'

# Execute with query parameters
orth run <api-slug> <path> -q key=value -q limit=5

# Execute with a JSON body and save the response
orth run <api-slug> <path> -X POST -b '{"key":"value"}' -o result.json
```

Useful commands:

| Command | Purpose |
|---|---|
| `orth login [--key <key>]` | Sign in through the browser, or save an API key |
| `orth logout` | Remove the saved key |
| `orth whoami [--json]` | Who the key in use belongs to (the saved key, or `ORTHOGONAL_API_KEY`) |
| `orth search "<need>"` | Find relevant APIs with natural language |
| `orth api list` | Browse all APIs |
| `orth api show <slug> [path]` | Inspect endpoints or one endpoint's parameters |
| `orth run <slug> <path>` | Execute an endpoint |
| `orth code <slug> <path>` | Generate TypeScript integration code |
| `orth balance [--json]` | Credits of whoever the key bills (a personal key: your account; an organization key: its shared credits), and where to add more |
| `orth usage [--limit <n>] [--days <n>] [--json]` | Recent paid calls and total spent |

Run `orth <command> --help` for the current flags and syntax.

## MCP

Connect any MCP-compatible client to:

```json
{
  "mcpServers": {
    "orthogonal": {
      "url": "https://www.orthogonal.com/mcp"
    }
  }
}
```

- `https://www.orthogonal.com/mcp` signs you in as yourself (OAuth), and your account pays for calls. It also takes an API key through mcp-remote with an `x-api-key` header (setup: https://www.orthogonal.com/docs/mcp/setup); then whoever the key bills pays.
- `https://www.orthogonal.com/org` signs you in for an organization (OAuth only), and that organization pays.

| Connection | Tools |
|---|---|
| Every connection | `search`, `get_details`, `quote`, `use`, `integrate`, `batch_use`, `batch_get_details` |
| OAuth sign-in (`/mcp` or `/org`) | Also `account`, `usage`, `payouts`, `onboarding_tools`, `onboarding` |
| API key (mcp-remote) | Only the seven API tools. For account, usage, payouts and onboarding, sign in with OAuth |

- `account`: who you are, the organization this connection acts for, your organizations and your role in each, who pays for calls, the credit balance, and links to add credits and to the dashboard.
- `usage`: recent paid calls and total spent. Input `days` (1-365, default 30) and `limit` (1-100, default 20).
- `payouts`: a seller organization's payout status, amount owed, earnings and payouts made. On a personal sign-in it answers for your seller organization.
- `onboarding_tools`: the how-to and every onboarding tool's input schema. Read it before `onboarding`.
- `onboarding`: runs one onboarding tool: `list_organizations`, `list_requests`, `create_request`, `get_request`, `start_onboarding`, `onboarding_status`, `stop_onboarding`, `get_setup`, `set_base_url`, `set_prices`, `leave_out`, `confirm_setup`, `answer_approval`, `run_checks`, `submit_for_review`, `withdraw_submission`, `resubmit_request`, `cancel_request`, `listing_status`, `start_update`, `discard_update`, plus the setup tools Orth (Orthogonal's onboarding agent) uses, for doing the setup with your own agent.

For API calls, follow the same discover → inspect → quote → run workflow.

## List your own API

API providers list their API in the dashboard at https://www.orthogonal.com/account/listings, or with their own agent over MCP (an OAuth sign-in; the `onboarding_tools` and `onboarding` tools). Guide: https://www.orthogonal.com/docs/list-your-api

- An API is published by a seller organization, not a personal account, and its earnings and Stripe payouts go to that organization. A team may list several APIs.
- The person creates the seller organization in the dashboard (Your listings, then Sell APIs or Both as its purpose); agents cannot create one. If the onboarding tools answer that the person is not an admin of an organization that sells APIs, send them to https://www.orthogonal.com/account/listings.
- Orthogonal's staff approve the request first; nothing is emailed, so check the status. Then Orth, Orthogonal's onboarding agent, reads the docs and drafts the base URL, endpoints and prices, confirms the setup, the checks make one real call to every endpoint, and the provider submits the tested API for Orthogonal's final review. Orth decides every open choice itself and asks nothing; only adding the key and submitting are the provider's.

The agent loop over MCP, through the `onboarding` tool:

1. Find the request: `list_requests` shows the organization's request and its `requestId`. With none, run `create_request` { apiName, documentationUrl, useCase? } once.
2. Check the status: `onboarding_status` with the `requestId`. Read `nextStep`.
3. Run the step: `nextStep.tool` (its tool and input, with the `requestId`). Submit (`submit_for_review`) only once your user read the final report (`get_setup`) and wants it listed.
4. Repeat from step 2 until `nextStep.action` is `done` (the API is live, declined or cancelled).
5. To change a live API: `listing_status` shows its versions; `start_update` opens the next version (`sync: true` has Orth check it against the docs, or `message` says what to change). Buyers keep the live version until Orthogonal accepts the new one; loop from step 2 to submit it. A version that changes nothing is closed with `discard_update`; the live version stays.

Never ask for, read, accept or pass the API's key. Only the person adds it, in the dashboard (Add credential securely in Your listings). Payouts are set up in the browser at https://www.orthogonal.com/account/payouts; the `payouts` tool reports their status and the earnings.

## SDK

```bash
npm install @orth/sdk
```

```typescript
import Orthogonal from "@orth/sdk";

const orth = new Orthogonal({
  apiKey: process.env.ORTHOGONAL_API_KEY,
});

const result = await orth.run({
  api: "apollo",
  path: "/v1/people/search",
  query: { title: "CTO", limit: 5 },
});

console.log(result.data, result.price);
```

## REST API

Base URL: `https://www.orthogonal.com`

Authenticate with `Authorization: Bearer $ORTHOGONAL_API_KEY`.

| Method | Endpoint | Purpose |
|---|---|---|
| `POST` | `/v1/search` | Discover APIs using natural language |
| `POST` | `/v1/details` | Get an endpoint's full schema and price |
| `GET` | `/v1/list-endpoints` | Browse the complete catalog |
| `POST` | `/v1/run` | Execute an API call |
| `POST` | `/v1/integrate` | Generate integration code |

For machine-readable discovery without authentication:

- `https://www.orthogonal.com/discover` returns the catalog as JSON, including endpoint schemas, pricing, and payment URLs.
- `https://www.orthogonal.com/openapi.json` returns the catalog as an OpenAPI 3.1 document.

Example:

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H "Authorization: Bearer $ORTHOGONAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"api":"olostep","path":"/v1/scrapes","body":{"url_to_scrape":"https://example.com"}}'
```

## Pricing and payments

Calls are metered individually with no subscription or per-provider account. Search and details show endpoint pricing, and run responses include the charged price. Use prepaid credits by default; payable catalog endpoints also support x402 with USDC on Base and MPP with USDC.e on Tempo.

Do not blindly repeat a paid call after an ambiguous timeout or interrupted response. Check usage first, then retry only when the earlier call is known not to have completed.

On `/v1/run`, send an `Idempotency-Key` header, one per logical call: a retry with the same key is run and billed once. A 409 `IN_PROGRESS` means the call is still running (retry later with the same key); `ALREADY_PROCESSED` means it completed and was billed (its `requestId` is in the body; the response is not replayed); `RESERVATION_CONFLICT` or `RESERVATION_SETTLED` means use a new key.

### Check balance and email a Stripe top-up link

Use the API key returned by signup. Check balance and available packages:

```bash
curl --fail-with-body --silent --show-error 'https://api.orthogonal.com/v1/credits/balance' \
  -H "Authorization: Bearer $ORTHOGONAL_API_KEY"
curl --fail-with-body --silent --show-error 'https://api.orthogonal.com/v1/credits/pricing'
```

Read the current package price, including its processing fee, and ask the user before requesting a payment email. With their approval, request a link (this example adds $25 of credits and currently costs $26.25 including the 5% fee):

```bash
curl --fail-with-body --silent --show-error \
  -X POST 'https://api.orthogonal.com/v1/credits/email-payment-link' \
  -H "Authorization: Bearer $ORTHOGONAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"credits":25}'
```

The endpoint sends the Stripe checkout link only to the account's current verified primary email. Do not supply an email, account ID, organization ID, or redirect URL. It requires a personal API key; organization top-ups use the dashboard.

Check `emailSent`, `email`, `totalLabel`, and `checkoutUrl` in the response. If `emailSent` is false, give the user the existing checkout link instead of repeatedly requesting more emails. Requests are limited to one per minute and five per account per day; honor HTTP 429 and do not retry in a loop.

Creating a link does not charge a card or add credits. The user completes Stripe checkout; never enter payment details or complete payment on their behalf without explicit authorization. After they confirm payment, check `GET /v1/credits/balance` again. Payment processing can take a moment; avoid rapid polling. Keep API keys and checkout URLs out of shared logs.

## Links

- API catalog: https://www.orthogonal.com/catalog
- Documentation: https://www.orthogonal.com/docs
- Dashboard: https://www.orthogonal.com/account/overview
- List your API: https://www.orthogonal.com/docs/list-your-api