Advanced

API Reference

Complete API documentation for Forge

Agent Chat API

POST /api/agent/chat

Send a message to the AI agent and receive a response.

Request Body:

{
  "message": "Check my SOL balance",
  "walletAddress": "7xKXY...",
  "conversationId": "optional-conversation-id"
}

Response:

{
  "response": "Your SOL balance is 5.23 SOL",
  "conversationId": "conv-123",
  "actions": [
    {
      "type": "balance_check",
      "result": {
        "balance": 5230000000,
        "token": "SOL"
      }
    }
  ]
}

Status Codes:

• 200: Success
• 400: Bad Request (invalid parameters)
• 401: Unauthorized (missing API key)
• 500: Server Error

Wallet APIs

GET /api/wallet/balance

Get SOL and token balances for a wallet.

Query Parameters:

address: string (required)

Response:

{
  "sol": 5230000000,
  "tokens": [
    {
      "mint": "EPjFW...",
      "symbol": "USDC",
      "balance": 100000000,
      "decimals": 6
    }
  ]
}

GET /api/wallet/transactions

Get transaction history for a wallet.

Query Parameters:

address: string (required)
limit: number (optional, default: 10)
before: string (optional, transaction signature)

Response:

{
  "transactions": [
    {
      "signature": "5jw7...",
      "blockTime": 1699564800,
      "status": "success",
      "fee": 5000,
      "type": "transfer"
    }
  ]
}

Token APIs

POST /api/tokens/transfer

Transfer SPL tokens to another address.

Request Body:

{
  "from": "SENDER_ADDRESS",
  "to": "RECIPIENT_ADDRESS",
  "mint": "TOKEN_MINT_ADDRESS",
  "amount": 1000000,
  "decimals": 6
}

Response:

{
  "signature": "5jw7xK...",
  "status": "confirmed"
}

Rate Limits

Default Rate Limits

• Agent Chat: 60 requests per minute
• Wallet APIs: 100 requests per minute
• Token Operations: 30 requests per minute
• Heavy Operations: 10 requests per minute

Rate limits can be increased with custom RPC endpoints.

Authentication

API Key Authentication

Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY

For development, API keys can be generated in your environment configuration.

Error Responses

Standard Error Format

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient SOL balance for transaction",
    "details": {
      "required": 1000000000,
      "available": 500000000
    }
  }
}

Webhooks

Transaction Notifications

Configure webhooks to receive real-time transaction updates:

POST https://your-endpoint.com/webhook
{
  "type": "transaction.confirmed",
  "signature": "5jw7xK...",
  "wallet": "7xKXY...",
  "timestamp": 1699564800
}

SDK Examples

JavaScript/TypeScript

import axios from 'axios';

const response = await axios.post('/api/agent/chat', {
  message: 'Check my balance',
  walletAddress: '7xKXY...'
}, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

Python

import requests

response = requests.post('http://localhost:3000/api/agent/chat', 
  json={
    'message': 'Check my balance',
    'walletAddress': '7xKXY...'
  },
  headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

← Previous: Misc Plugin Next: Architecture →