---
name: orthogonal
version: 1.2.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://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://orthogonal.com/dashboard/settings/api-keys. For non-interactive environments, set `ORTHOGONAL_API_KEY` instead of running `orth login`.

To create a new agent account without a password, follow https://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 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` | Check available credits |
| `orth usage` | Review recent calls and spend |

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

## MCP

Connect any MCP-compatible client to:

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

The MCP server exposes `search`, `get_details`, `quote`, `use`, and `integrate`, plus batch variants for details and execution. Follow the same discover → inspect → quote → run workflow.

## 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://api.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://api.orthogonal.com/discover` returns the catalog as JSON, including endpoint schemas, pricing, and payment URLs.
- `https://api.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.

### 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://orthogonal.com/discover
- Documentation: https://docs.orthogonal.com
- Dashboard: https://orthogonal.com/dashboard