Authentication

The Blowfish Agent API uses wallet-based challenge-response authentication. Your agent proves ownership of a Solana wallet by signing a server-issued nonce, then receives a short-lived JWT for subsequent requests.

Flow overview

Agent                          Blowfish API
  |                                |
  |-- POST /api/auth/challenge --> |  (send wallet address)
  |<-- nonce --------------------- |
  |                                |
  |  sign("Sign this message to   |
  |   authenticate: {nonce}")      |
  |                                |
  |-- POST /api/auth/verify -----> |  (wallet + nonce + signature)
  |<-- JWT token ----------------- |
  |                                |
  |-- GET /api/v1/tokens/ -------> |  (Authorization: Bearer <JWT>)
  |<-- data ---------------------- |

Step 1: Request a challenge

Send your wallet address to receive a nonce. The nonce is stored server-side with a 5-minute TTL. Each new challenge request for the same wallet overwrites the previous nonce.

const response = await fetch("https://api-blowfish.neuko.ai/api/auth/challenge", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ wallet: walletAddress }),
});

const { nonce } = await response.json();

Step 2: Sign the nonce

Construct the message Sign this message to authenticate: <nonce> and create an ed25519 detached signature, then base58-encode it.

Using @solana/web3.js + tweetnacl + bs58

import { Keypair } from "@solana/web3.js";
import nacl from "tweetnacl";
import bs58 from "bs58";

const message = `Sign this message to authenticate: ${nonce}`;
const messageBytes = new TextEncoder().encode(message);

// Sign with your wallet's secret key
const signatureBytes = nacl.sign.detached(messageBytes, keypair.secretKey);
const signature = bs58.encode(signatureBytes);

Step 3: Verify and get JWT

Submit the wallet address, nonce, and signature. The nonce is consumed on verification -- it cannot be reused.

const verifyResponse = await fetch("https://api-blowfish.neuko.ai/api/auth/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ wallet: walletAddress, nonce, signature }),
});

const { token } = await verifyResponse.json();

Step 4: Use the JWT

Pass the JWT as a Bearer token in the Authorization header on all authenticated requests.

const tokensResponse = await fetch("https://api-blowfish.neuko.ai/api/v1/tokens/", {
  headers: { Authorization: `Bearer ${token}` },
});

const data = await tokensResponse.json();

JWT details

Property	Value
Algorithm	HS256
Expiry	15 minutes
sub claim	Wallet address
scope claim	["read", "trade"]

Full TypeScript example

import { Keypair } from "@solana/web3.js";
import nacl from "tweetnacl";
import bs58 from "bs58";

const API_BASE = "https://api-blowfish.neuko.ai";

async function authenticate(keypair: Keypair): Promise<string> {
  const walletAddress = keypair.publicKey.toBase58();

  // 1. Get challenge nonce
  const challengeRes = await fetch(`${API_BASE}/api/auth/challenge`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ wallet: walletAddress }),
  });

  if (!challengeRes.ok) {
    throw new Error(`Challenge failed: ${challengeRes.status}`);
  }

  const { nonce } = await challengeRes.json();

  // 2. Sign the nonce
  const message = `Sign this message to authenticate: ${nonce}`;
  const messageBytes = new TextEncoder().encode(message);
  const signatureBytes = nacl.sign.detached(messageBytes, keypair.secretKey);
  const signature = bs58.encode(signatureBytes);

  // 3. Verify and get JWT
  const verifyRes = await fetch(`${API_BASE}/api/auth/verify`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ wallet: walletAddress, nonce, signature }),
  });

  if (!verifyRes.ok) {
    throw new Error(`Verification failed: ${verifyRes.status}`);
  }

  const { token } = await verifyRes.json();
  return token;
}

Error handling

Error	Cause	Resolution
Invalid wallet address format	Malformed base58 address	Check wallet address encoding
Invalid or expired nonce	Nonce TTL exceeded (5 min) or already consumed	Request a new challenge
Invalid signature	Signature verification failed	Ensure you're signing the exact message format with the correct private key
Invalid or expired token	JWT expired (15 min)	Re-authenticate to get a new JWT

Security notes

• Nonces are single-use -- consumed atomically on verification

• Each wallet can only have one active nonce at a time

• JWTs are short-lived (15 min) to limit exposure

• Always store private keys securely; never transmit them over the network