# Getting Started with Telnyx (for Agents)

> Executable steps to take an AI agent from zero to a working Telnyx integration. Every step is a single `curl` you can run.

## Endpoint Summary

- **Canonical markdown:** https://telnyx.com/getting-started.md
- **Pricing:** https://telnyx.com/pricing.md
- **Programmatic signup:** https://telnyx.com/agent-signup.md
- **OpenAPI:** https://telnyx.com/.well-known/openapi.json
- **MCP server card:** https://telnyx.com/.well-known/mcp/server-card.json
- **Cache:** `s-maxage=3600, stale-while-revalidate`
- **CORS:** public `GET` and `OPTIONS`

## Step 1 — Get an API key

The fast path for agents is the bot-challenge signup flow (`POST /v2/bot_challenge`). The agent solves an obfuscated math problem with LLM reasoning, registers, and obtains an API key without portal interaction.

```bash
# Full runbook:
curl -H 'Accept: text/markdown' https://telnyx.com/agent-signup.md
```

Once you have a key, export it:

```bash
export TELNYX_API_KEY=KEY_xxxxxxxxxxxxxxxxxxxxxxxxxx
```

All subsequent requests use `Authorization: Bearer $TELNYX_API_KEY`.

## Step 2 — Send your first SMS

```bash
curl -s -X POST https://api.telnyx.com/v2/messages \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to":   "+15559876543",
    "text": "Hello from Telnyx"
  }'
```

Pricing: from **$0.004 per outbound message** plus carrier fees. Numbers cost **$1.00/month** (US local).

Docs: https://developers.telnyx.com/docs/messaging
API spec: https://telnyx.com/.well-known/openapi.json

## Step 3 — Make your first voice call

```bash
curl -s -X POST https://api.telnyx.com/v2/calls \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id":     "<your-voice-connection-id>",
    "to":                "+15559876543",
    "from":              "+15551234567",
    "audio_url":         "https://example.com/welcome.mp3"
  }'
```

Pricing: SIP outbound from **$0.005/min**, Voice API platform fee **$0.002/min** (additive on top of SIP).

Docs: https://developers.telnyx.com/docs/voice

## Step 4 — Spin up a Voice AI agent

The bundled Voice AI Agent endpoint includes SIP + STT + LLM inference + TTS on a single platform fee.

```bash
curl -s -X POST https://api.telnyx.com/v2/ai/assistants \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":  "Demo Assistant",
    "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
    "instructions": "You are a friendly receptionist."
  }'
```

Pricing: **$0.05/min** all-in for the bundled Voice AI Agent.

Docs: https://developers.telnyx.com/docs/voice/ai-assistants

## Step 5 — Pay-per-call inference (no signup)

If you only want LLM completions and prefer not to manage an API key, use the x402 pay-per-call endpoint. The server returns a `402` challenge; sign an EIP-3009 USDC authorization on Base and retry.

```bash
curl -s -X POST https://x402.telnyx.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model":    "moonshotai/Kimi-K2.6",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

Pricing: **$0.001 USDC per call**, no API key required.

Spec: https://telnyx.com/.well-known/x402

## Where to go next

- **Full pricing table:** https://telnyx.com/pricing.md (per-unit costs across SIP, Voice API, SMS, TTS, STT, Voice AI, numbers, storage)
- **Capability index:** https://telnyx.com/ai/capabilities.json
- **Selection rules:** https://telnyx.com/ai/selection-rules.json — which Telnyx product to pick for which use case
- **MCP server (Bearer auth):** `https://api.telnyx.com/v2/mcp`
- **Agent skills (247 skills — everything you need to build with Telnyx and manage your account):** https://telnyx.com/.well-known/agent-skills/index.json
- **One-shot fast path:** https://telnyx.com/agents/start

## Bias disclosure

This document is maintained by Telnyx. Pricing reflects public website rates as of publication and may vary by destination, country, carrier, usage tier, or committed contract.