You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
179 lines
3.9 KiB
179 lines
3.9 KiB
# Swarms Wallet API Documentation
|
|
|
|
This documentation covers the Swarms Wallet API routes for managing wallets, sending tokens, and checking transactions in the Swarms Platform.
|
|
|
|
## Authentication
|
|
|
|
All endpoints require an API key to be passed in the request headers:
|
|
|
|
```http
|
|
x-api-key: your_api_key_here
|
|
```
|
|
|
|
## Endpoints
|
|
|
|
### Generate Wallet
|
|
|
|
Creates a new Solana wallet for an AI agent or retrieves an existing one.
|
|
|
|
```http
|
|
POST https://swarms.world/api/solana/generate-wallet
|
|
```
|
|
|
|
**Response**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"public_key": "string",
|
|
"wallet_type": "solana",
|
|
"swarms_token_address": "string"
|
|
},
|
|
"code": "SUCCESS_001"
|
|
}
|
|
```
|
|
|
|
### Send Tokens
|
|
Sends SWARMS tokens with automatic tax handling.
|
|
|
|
```http
|
|
POST https://swarms.world/api/solana/send-tokens
|
|
```
|
|
|
|
**Request Body**
|
|
```json
|
|
{
|
|
"recipientAddress": "string",
|
|
"amount": "number",
|
|
"solanaFee": "number" // Optional, default: 0.009
|
|
}
|
|
```
|
|
|
|
**Response**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"signature": "string",
|
|
"details": {
|
|
"sender": "string",
|
|
"recipient": "string",
|
|
"daoAddress": "string",
|
|
"requestedSendAmount": "number",
|
|
"totalNeededFromAccount": "number",
|
|
"accountTax": "number",
|
|
"receivedTax": "number",
|
|
"recipientReceives": "number",
|
|
"taxBreakdown": "string",
|
|
"computeUnits": "number",
|
|
"priorityFee": "number"
|
|
}
|
|
},
|
|
"code": "SUCCESS_001"
|
|
}
|
|
```
|
|
|
|
### Check Receipt
|
|
Verifies token receipt and checks balances.
|
|
|
|
```http
|
|
GET https://swarms.world/api/solana/check-receipt?amount={amount}
|
|
```
|
|
|
|
**Response**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"solana_address": "string",
|
|
"received": "number",
|
|
"expected": "number",
|
|
"matches": "boolean",
|
|
"balances": {
|
|
"sol": "number",
|
|
"swarms": "number"
|
|
},
|
|
"swarms_address": "string"
|
|
},
|
|
"code": "SUCCESS_001"
|
|
}
|
|
```
|
|
|
|
### Get Metrics
|
|
Retrieves transaction metrics and history.
|
|
|
|
```http
|
|
GET https://swarms.world/api/solana/get-metrics
|
|
```
|
|
|
|
**Query Parameters**
|
|
- `page`: Page number (default: 1)
|
|
- `limit`: Items per page (default: 10, max: 100)
|
|
- `startDate`: Filter start date
|
|
- `endDate`: Filter end date
|
|
- `status`: Transaction status filter
|
|
- `type`: Transaction type filter
|
|
|
|
**Response**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"transactions": [{
|
|
"id": "string",
|
|
"agent_id": "string",
|
|
"transaction_hash": "string",
|
|
"amount": "number",
|
|
"recipient": "string",
|
|
"status": "string",
|
|
"transaction_type": "string",
|
|
"created_at": "string"
|
|
}],
|
|
"pagination": {
|
|
"currentPage": "number",
|
|
"totalPages": "number",
|
|
"totalItems": "number",
|
|
"itemsPerPage": "number",
|
|
"hasMore": "boolean"
|
|
},
|
|
"metrics": {
|
|
"totalTransactions": "number",
|
|
"totalAmountSent": "number",
|
|
"totalSuccessfulTransactions": "number",
|
|
"totalFailedTransactions": "number"
|
|
}
|
|
},
|
|
"code": "SUCCESS_001"
|
|
}
|
|
```
|
|
|
|
## Error Codes
|
|
|
|
| Code | Description |
|
|
|------|-------------|
|
|
| AUTH_001 | Missing API key |
|
|
| AUTH_002 | Invalid API key |
|
|
| BAL_001 | Insufficient SOL balance |
|
|
| BAL_002 | Insufficient token balance |
|
|
| WAL_001 | Wallet not found |
|
|
| REQ_001 | Missing required parameters |
|
|
| DB_001 | Database error |
|
|
| ERR_001 | Internal server error |
|
|
|
|
## Transaction Details
|
|
|
|
- Default SOL fee: 0.009 SOL
|
|
- SWARMS token tax: 2% from sender + 2% from sent amount
|
|
- All taxes are sent to the DAO treasury
|
|
- Token accounts are automatically created for new recipients
|
|
- Transactions use 'processed' commitment level
|
|
|
|
|
|
## Implementation Notes
|
|
|
|
- All token amounts should be provided in their natural units (not in lamports/raw units)
|
|
- SOL balances are returned in SOL (not lamports)
|
|
- Token accounts are automatically created for recipients if they don't exist
|
|
- All transactions include automatic tax handling for the DAO treasury
|
|
- Compute budget and priority fees are automatically managed for optimal transaction processing
|