Authentication and keys

API keys

Keys look like tide_ followed by 32 letters and digits. Create them in the developer portal 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%3A%3Asui%3A%3ASUI?api-key=YOUR_API_KEY"

curl "https://api.tide.ad/v1/coins/0x2%3A%3Asui%3A%3ASUI" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://api.tide.ad/v1/coins/0x2%3A%3Asui%3A%3ASUI" \
  -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. Developer portal sign-in uses the same two calls with /v0/auth/verify, which returns a session token that starts with tsess_.

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 on the key in the developer portal. 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.