Authentication and keys

API keys

Keys look like tide_ followed by 32 letters and digits. Create them with the Get an API key link at the top of the page, by signing in with a Sui wallet. A key is shown once, so copy it when you make it. tide stores only a hash.

Pass the key in any of three ways.

curl "https://api.tide.ad/v1/coins/0x2::sui::SUI?api-key=YOUR_API_KEY"

curl "https://api.tide.ad/v1/coins/0x2::sui::SUI" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://api.tide.ad/v1/coins/0x2::sui::SUI" \
  -H "Authorization: Bearer YOUR_API_KEY"

The header forms keep the key out of logs and browser history. Use them from servers. Never ship a key in a public web page without an allowed origin rule on it.

The keyless tier

With no key, calls are counted per client IP: 2 requests a second and 1,000 credits a day. Streams and webhooks need a key. Every keyless response has an x-tide-hint header that points to the free key page.

Keys for agents

An agent can get a Free key with one signed call. No email and no payment. It signs a challenge with any Sui key.

1. POST /v0/auth/nonce with { "address": "0x..." } returns a message to sign.
2. Sign the message as a Sui personal message. Any signature scheme works, including zkLogin and multisig.
3. POST /v0/keys/agent with { "address": "0x...", "signature": "..." } returns a key.

curl -X POST "https://api.tide.ad/v0/auth/nonce" \
  -H "content-type: application/json" \
  -d '{ "address": "0xYOUR_ADDRESS" }'

# sign the returned message with your Sui key, then:

curl -X POST "https://api.tide.ad/v0/keys/agent" \
  -H "content-type: application/json" \
  -d '{ "address": "0xYOUR_ADDRESS", "signature": "SIGNATURE" }'

The key belongs to that address. Keys made this way are Free plan keys. Signing in on tide.ad uses the same two calls with /v0/auth/verify, which returns a session token that starts with tsess_.

Paying without a key

A request with no key over the keyless daily limit, or with a key that is out of credits, gets 402 Payment Required with the offers to pay in USDC. Pay one, retry the same request, and the response carries an X-Tide-Api-Key header.

That key is derived from the paying Sui address, the same key every time. Use it as Authorization: Bearer for the rest of the session. Details, offers and prices: Pay with USDC.

curl -i "https://api.tide.ad/v1/coins/0x2::sui::SUI"
# HTTP/2 402, with a payment-required header and the offers in the body

Allowed origins and IPs

Each key can carry a list of allowed origins and a list of allowed IPs. A browser call from another origin, or any call from another IP, fails with forbidden_origin. Set the lists when you create or edit a key. An empty list allows everything.

Response headers

Account methods

These calls manage keys and read usage. They use a session token or sign-in, not credits.