Skip to main content
This guide walks you through authenticating your AI agent with Knot and making your first API call. The entire process takes under five minutes.

​
Prerequisites

  • An email address dedicated to your agent
  • The ability to receive and read emails from that address (or manual OTP retrieval during development)

​
Authentication flow

Knot uses a passwordless email OTP flow. Your agent never manages a private key — it authenticates with an email address and receives a JWT token for all subsequent API calls.
1

Request an OTP

Send a POST request to start the authentication process. Replace agent@example.com with your agent’s email address.
curl -X POST https://api.useknot.xyz/connect/start \
  -H "Content-Type: application/json" \
  -d '{"email": "agent@example.com"}'
Knot responds with an otpId that you’ll use in the next step:
{
  "status": true,
  "statusCode": 200,
  "message": "OTP sent successfully.",
  "data": {
    "otpId": "uuid-of-otp-request"
  }
}
2

Retrieve the OTP code

Check the email inbox for a 6-digit OTP code. The code expires after 10 minutes.
During development you can retrieve the OTP manually. In production, your agent should read the OTP from the email inbox automatically using an email API or IMAP.
3

Complete authentication

Submit the OTP code along with the otpId from step 1:
curl -X POST https://api.useknot.xyz/connect/complete \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent@example.com",
    "otpId": "uuid-from-start",
    "otpCode": "123456"
  }'
On success, Knot returns your API token and Solana wallet address:
{
  "status": true,
  "statusCode": 200,
  "message": "Authentication successful. Wallet created.",
  "data": {
    "apiToken": "eyJhbGciOiJIUzI1NiIs...",
    "solanaAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "username": "agent_abc123",
    "isNewAgent": true
  }
}
4

Store your token

Save the apiToken value securely. You’ll include it as a Bearer token in every subsequent API request.
Treat your apiToken like a password. Do not log it, commit it to source control, or expose it in client-side code.

​
What happens on first authentication

When your agent authenticates for the first time, Knot automatically:
  1. Creates a new Solana wallet inside the TEE
  2. Provisions a sub-organization to isolate your agent’s keys
  3. Applies the default policy (spending limits, feature access)
  4. Returns your agent’s Solana address and JWT token
On subsequent authentications, the same wallet and address are returned — no new wallet is created.

​
Make your first API call

Use your token to check your wallet balance: 
curl https://api.useknot.xyz/wallets/me/balances \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
A new wallet will show zero balances: 
{
  "status": true,
  "data": {
    "solanaAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "sol": {
      "balance": 0,
      "usdValue": 0
    },
    "tokens": [],
    "totalUsdValue": 0
  }
}
Fund your wallet by sending SOL or SPL tokens to the solanaAddress returned above.

​
Token expiration

Tokens expire after 7 days (168 hours) by default. You can configure a different expiration per agent via the sessionExpirationHours field in your agent’s policy. When a token expires, your agent receives a 401 Unauthorized response. Handle this by re-running the OTP flow to obtain a new token.
Implement proactive token refresh before the expiration window closes. Store the token issue time alongside the token itself, and trigger re-authentication at least one hour before expiry.

​
Next steps

Transfer tokens

Send SOL and SPL tokens to any Solana address.

Trade tokens

Swap tokens via the Jupiter aggregator with MEV protection.

Policy engine

Configure spending limits, daily caps, and recipient whitelists.

API reference

Explore all available endpoints with full request and response examples.