Encrypted, Tor & I2P endpoints

Base URLs

Four addresses lead to the same API. Use the one that fits your network, with the same API key and the same requests.

• An OpenAI SDK takes the base URL as shown, with /v1. An Anthropic SDK takes it without /v1.
• To check an address, read the reply headers of https://api.shannon-ai.com: Onion-Location carries the onion address and X-I2P-Location the I2P address. The onion address starts with shannon.

Which routes work

Every /v1 route answers on all four addresses:

• POST /v1/chat/completions
• POST /v1/responses
• POST /v1/messages
• POST /v1/messages/count_tokens
• POST /v1/tokenize
• GET /v1/models

GET /v1/models needs no key, which makes it a quick test that your proxy reaches the API.

What is the same and what differs

Balance and limits are described on their own page. Limits and balance

cURL through Tor

Run a Tor client on your machine. It offers a SOCKS5 proxy on 127.0.0.1:9050. --socks5-hostname hands the .onion name to that proxy.

# 1. Is the onion service reachable? No key needed.
curl --socks5-hostname 127.0.0.1:9050 http://shannonmd773o5vxz75byha5rkea7nzr3srotw46uwythq3pjl6y4cad.onion/v1/models

# 2. A streamed chat call. -N prints the stream as it arrives.
curl -N --socks5-hostname 127.0.0.1:9050 http://shannonmd773o5vxz75byha5rkea7nzr3srotw46uwythq3pjl6y4cad.onion/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "stream": true,
    "messages": [{"role": "user", "content": "Hello over Tor"}]
  }'

cURL through I2P

Run an I2P router on your machine. It offers an HTTP proxy on 127.0.0.1:4444, which takes the .b32.i2p name as it is.

# 1. Is the eepsite reachable? No key needed.
curl --proxy http://127.0.0.1:4444 http://acvnvkdea4xaczzjap7chysqqi4kkvp2eorfwkasindzmjpa47da.b32.i2p/v1/models

# 2. A streamed chat call.
curl -N --proxy http://127.0.0.1:4444 http://acvnvkdea4xaczzjap7chysqqi4kkvp2eorfwkasindzmjpa47da.b32.i2p/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "stream": true,
    "messages": [{"role": "user", "content": "Hello over I2P"}]
  }'

SDK base URL

An SDK needs two changes: the base URL of the network, and an HTTP client that goes through the proxy. In Python both official SDKs take an httpx client. For a SOCKS proxy install httpx[socks].

# pip install openai "httpx[socks]"
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="http://shannonmd773o5vxz75byha5rkea7nzr3srotw46uwythq3pjl6y4cad.onion/v1",
    http_client=httpx.Client(proxy="socks5h://127.0.0.1:9050", timeout=600),
)

stream = client.chat.completions.create(
    model="shannon-3",
    messages=[{"role": "user", "content": "Hello over Tor"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

# pip install openai
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="http://acvnvkdea4xaczzjap7chysqqi4kkvp2eorfwkasindzmjpa47da.b32.i2p/v1",
    http_client=httpx.Client(proxy="http://127.0.0.1:4444", timeout=600),
)

stream = client.chat.completions.create(
    model="shannon-3",
    messages=[{"role": "user", "content": "Hello over I2P"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

# pip install anthropic "httpx[socks]"
import anthropic
import httpx

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="http://shannonmd773o5vxz75byha5rkea7nzr3srotw46uwythq3pjl6y4cad.onion",
    http_client=httpx.Client(proxy="socks5h://127.0.0.1:9050", timeout=600),
)

with client.messages.stream(
    model="shannon-1.6-lite",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello over Tor"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Streaming and keep-alive on slow links

Streaming works over both networks. While a stream is open and the model has nothing to send yet, the API sends a keep-alive, so the connection does not look dead to a proxy or to your client.

• Send "stream": true. A streamed reply starts to arrive as soon as the model writes, and the keep-alive shows that the request is still being worked on. A non-streamed reply sends nothing until the whole answer is ready.
• Give the client a long read timeout. The samples use 600 seconds. A timeout shorter than 15 seconds can end a stream between two keep-alives.
• Let your SSE reader skip comment lines and ping events. The SDKs do this already.
• Do not resend a request the moment a connection drops. A request that reached the API runs to its end and is counted, also when the connection is gone.
• Test the path with GET /v1/models first. It needs no key and returns a short JSON list.

Connection problems

Every other error is the same as on the clear web. Error Handling

Your key without JavaScript

Shannon also has a website without JavaScript, reachable on the clear web, as an onion service and as an eepsite. Its /keys page shows your API key and lets you rotate it, so you can get a key without leaving Tor or I2P. encrypted.shannon-ai.com/keys

The addresses of that website on all three networks are listed here: Encrypted access