Postman Collection

A complete Postman collection is available for testing and exploring the Nexgent API.

Download

The collection files are located in the repository:

packages/backend/postman/
├── Nexgent-API.postman_collection.json
├── Nexgent-API.postman_environment.json
└── README.md

Direct links:

• Collection JSON (opens in a new tab)
• Environment JSON (opens in a new tab)

Quick Start

1. Import Collection

1. Open Postman
2. Click Import (top left)
3. Select Nexgent-API.postman_collection.json
4. Click Import

2. Import Environment

1. Click Import
2. Select Nexgent-API.postman_environment.json
3. Click Import
4. Select the environment from the dropdown (top right): "Nexgent API - Local Development"

3. Configure Environment

Click the eye icon next to the environment dropdown and update:

4. Start Testing

1. Run Register or Login to get tokens
2. Tokens are automatically stored in the environment
3. All protected endpoints will use the stored token

Collection Structure

The collection is organized into folders:

Nexgent AI API/
├── Authentication/
│   ├── Register
│   ├── Login
│   ├── Refresh Token
│   ├── Get Current User
│   └── Logout
├── API Keys/
│   ├── Create API Key
│   ├── List API Keys
│   ├── Get API Key
│   └── Delete API Key
├── Agents/
│   ├── Create Agent
│   ├── List Agents
│   ├── Get Agent
│   ├── Update Agent
│   ├── Delete Agent
│   ├── Get Agent Config
│   └── Update Agent Config
├── Agent Balances/
│   ├── List Agent Balances
│   └── ...
├── Agent Positions/
│   ├── Get Agent Positions
│   └── Close Position
├── Agent Transactions/
│   └── ...
├── Historical Swaps/
│   └── ...
├── Trading Signals/
│   ├── Create Signal (API Key)
│   ├── List Signals
│   └── ...
├── Wallets/
│   ├── List Wallets
│   ├── Assign Wallet
│   └── ...
├── Price Feeds/
│   └── Get SOL/USD Price
├── Data Sources/
│   └── Get Status
└── Health/
    ├── Health Check
    ├── Readiness
    └── Liveness

Environment Variables

Automatic Variables

These are automatically set by collection scripts:

Manual Variables

Set these yourself:

Authentication Flow

JWT Flow (Dashboard)

1. Register / Login
   └─► Tokens stored in environment

2. Protected Requests
   └─► Authorization header auto-populated

3. Token Expires
   └─► Use Refresh Token request

4. Logout
   └─► Tokens cleared from environment

API Key Flow (External)

1. Login with JWT
   └─► Get access token

2. Create API Key
   └─► API key stored in environment

3. Create Signal
   └─► Uses X-API-Key header

Request Examples

Create Trading Signal (API Key Auth)

POST {{base_url}}/api/v1/trading-signals
X-API-Key: {{api_key}}
Content-Type: application/json
 
{
  "tokenAddress": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "symbol": "BONK",
  "signalType": "buy",
  "signalStrength": 4,
  "source": "postman-test"
}

Get Agent Positions (JWT Auth)

GET {{base_url}}/api/v1/agent-positions/{{agent_id}}
Authorization: Bearer {{access_token}}

Automated Tests

Each request includes automated tests. Run the collection to verify:

Authentication Tests

• ✅ Status code is 201 (register) / 200 (login)
• ✅ Response has access token
• ✅ Response has refresh token
• ✅ Response has user object

Agent Tests

• ✅ Status code is correct
• ✅ Response has required fields
• ✅ User can only access own agents

Global Tests

• ✅ Response time is less than 5000ms

Running Collection

Run All Requests

1. Click the ... menu on the collection
2. Select Run collection
3. Configure iterations and delay
4. Click Run Nexgent AI API

Run Folder

1. Right-click a folder (e.g., "Authentication")
2. Select Run folder
3. Configure and run

Troubleshooting

"Access token not found"

Solution: Run Login or Register first.

"Invalid or expired refresh token"

Solution: Login again to get a new refresh token.

"Account is locked"

Solution: Wait 15 minutes or reset in database.

"Connection refused"

Solution: Ensure backend is running on the configured port.

"Agent not found"

Solution: Create an agent first, or check the agent_id variable.

Tips

1. Use Collection Runner for Testing

Run the entire collection to test all endpoints in sequence.

2. Pre-request Scripts

The collection uses pre-request scripts to:

• Ensure tokens are fresh
• Set dynamic timestamps
• Generate test data

3. Environment Switching

Create multiple environments for:

• Local development
• Staging
• Production