Authentication

Pool metadata, pool analytics, Explore data, protocol state, and compliance reads are public. Routes, positions, and other protected endpoints require credentials. Choose the credential that matches your client:

Client	Credential	Storage rule
Browser application	Wallet session in httpOnly cookies	Let the browser manage cookies; keep the CSRF token in memory
Backend, bot, or CLI	Long-lived `ss_...` API token	Store it in a secret manager or protected environment variable

Both flows begin with a wallet signature. The sign-in message includes the current Terms of Use and related disclosures. Successful verification records acceptance of that terms version.

Create a browser wallet session

Request a challenge

Send the wallet address to POST /auth/challenge.

curl --fail-with-body \
  "https://api.swap.shield.fi/auth/challenge" \
  --header "Content-Type: application/json" \
  --data '{"address":"aleo1..."}'

The response contains data.challenge_id, data.nonce, and data.message. Keep the challenge ID for verification.

Sign the returned message

Ask the wallet to sign the exact UTF-8 bytes in data.message. Do not reconstruct, trim, or normalize the message.Signing proves control of the address. It does not submit a transaction or spend a token record.

Verify the signature

Send the address, signature, and returned challenge ID to POST /auth/verify. The example stores the returned cookies in session.cookies.

curl --fail-with-body \
  "https://api.swap.shield.fi/auth/verify" \
  --header "Content-Type: application/json" \
  --cookie-jar session.cookies \
  --data '{"address":"aleo1...","signature":"sign1...","challenge_id":"YOUR_CHALLENGE_ID"}'

A successful response sets access and refresh tokens as httpOnly cookies. The JSON body returns the wallet address, expires_at, server_time, session details, and a CSRF token. Use expires_at - server_time to calculate the remaining lifetime.

Send authenticated requests

Include the cookie jar on subsequent requests. Add the CSRF token in X-CSRF-Token for state-changing session requests.

curl --fail-with-body \
  "https://api.swap.shield.fi/api-tokens" \
  --cookie session.cookies

Access cookies expire after 15 minutes. POST /auth/refresh rotates the refresh token and sets fresh cookies. If two refreshes race, one can return 409; retry the original API request after the successful refresh completes.

Create an API token for a backend

API-token creation requires an authenticated browser session and acceptance of the current Terms of Use. If a protected request returns 403 with code terms_required, repeat the wallet sign-in flow with a new challenge.

curl --fail-with-body \
  "https://api.swap.shield.fi/api-tokens" \
  --request POST \
  --cookie session.cookies \
  --header "Content-Type: application/json" \
  --header "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  --data '{"name":"market-data-worker","expires_in_days":30}'

The response shows the full ss_... token once. Store it before closing the response. Later list responses expose only token metadata and a prefix. Use the token as a bearer credential:

curl --fail-with-body \
  "https://api.swap.shield.fi/route?token_in=TOKEN_A&token_out=TOKEN_B&amount_in=1000000" \
  --header "Authorization: Bearer ss_YOUR_API_TOKEN"

Credential boundaries

A valid wallet signature establishes wallet control, not administrator authority.
API tokens cover protected data and route endpoints. API-token management and administrative endpoints require a wallet session.
WebSocket clients can request a short-lived ticket with a browser session or API token. They must renew authentication before the 60-second ticket expires.
Never place session cookies, CSRF tokens, or API tokens in URLs or logs.
Revoke a backend token with DELETE /api-tokens/{id} when it is no longer needed.
Use GET /auth/sessions and POST /auth/sessions/{session_id}/revoke to manage wallet sessions.
Use POST /auth/logout for the current session or POST /auth/logout-all for every wallet session.

Overview and access

Pools

Market discovery

Positions and claims

Tokens

Routing and protocol

Compliance

Diagnostics

Authentication and API tokens

Referrals

Test tokens

Create a browser wallet session

Create an API token for a backend

Credential boundaries

​Create a browser wallet session

​Create an API token for a backend

​Credential boundaries

Create a browser wallet session

Create an API token for a backend

Credential boundaries