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

After loginWithWallet, user-scoped resource routes use userId rather than wallet address. Resolve it for a wallet:

1. Build the token above from a SIWE message signed by that wallet.
2. Send POST /v1/users/login-with-wallet with walletAddress in the JSON body and the token in Authorization: Signature <signature-token>.
3. On success, use user.userId from the response.
4. If the API returns NO_USER, send POST /v1/users with walletAddress, username, and the same token as signatureString in the JSON body. createUser does not require Authorization; its response also contains user.userId.

For resource-owner routes, the supplied userId must match the account recovered from the signature. Call loginWithWallet before createUser; only create an account after NO_USER. 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>

Integrator API keys

For GET /integrators/v1/{integratorId} and its read-only /users, /revenue-summary, and /agents routes, X-Api-Key: ysk_... can be used instead of a SIWE signature. The key must belong to the same integrator identified in the request. If both credentials are sent, either valid matching credential is sufficient. Keys are not individually endpoint-scoped: any active key for that integrator can use all four routes.

Listing integrators and API-key or dashboard-member management routes still require a SIWE signature. For routes scoped to an integrator, the signer must be a member; adding or removing dashboard members requires the master user. On core API routes, X-Api-Key only adds integrator context where the route supports it; it never replaces that route’s authentication. On signed user routes, a valid key adds context only when the signed-in user was referred by that integrator. For other users, the key is ignored as context after validation; an invalid or origin-disallowed key is still rejected. On createUser, a valid key attributes the new account to the integrator.

Keys may have allowed origins. A configured origin list is checked against the request’s Origin header. Treat the key as a bearer secret: keep it server-side and never embed it in browser code.

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 HTTP status, exceptionType, 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.