API authentication

User-scoped endpoints require proof that the caller controls the user’s wallet. YieldSeeker uses a Sign-In with Ethereum message and its signature as the authentication token.

Create the token

1. Create a SIWE message for the user’s wallet.
2. Use an allowed authentication domain.
3. Set issued_at to no more than 30 days before the request.
4. Have the wallet sign the complete message.
5. Base64-encode a JSON object containing the message and its hexadecimal signature.

{
  "message": "<siwe-message>",
  "signature": "<hex-signature>"
}

Resolve your userId

Every user-scoped endpoint is addressed by userId, not wallet address. To find it for a given wallet:

1. Build the token above from a SIWE message signed by that wallet.
2. Call loginWithWallet with the wallet address and the token in the Authorization header.
3. On success, the response’s user.userId is the ID to use for that wallet going forward.
4. If the call fails with a NO_USER error, the wallet has no account yet. Call createUser with the same signature to create one; its response also returns user.userId.

Integrators should call loginWithWallet first and only fall back to createUser on NO_USER, so an existing account is never accidentally duplicated. See the generated API reference for both endpoints’ exact schemas.

Send the token

For the documented v1 API, send the complete value in the Authorization header:

Authorization: Signature <base64-signature-token>

The SDK route family also accepts X-Signature; do not substitute it for v1 requests unless that route’s documentation specifies it.

Integrator API keys

An optional X-Api-Key identifies an approved integrator. When present, it is validated against the request origin. Omit it for normal first-party requests.

Rejected requests

Requests can be rejected when the signature is missing or invalid, the SIWE domain is not allowed, expirationTime has passed, or issued_at is too old. Use the returned error code and message for diagnosis; do not retry an invalid credential.

A request can also be rejected for exceeding the operation’s rate limit, which returns a 429 with a Retry-After header rather than an authentication error.

Security

Never log signature tokens, private keys, seed phrases, or API keys. A signature proves control for its intended message, so construct and display the message before asking a user to sign it.