POST
/
agents
/
create
curl --request POST \
  --url https://api.magebank.ai/agents/create \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{
  "userid": "<string>",
  "walletaddress": "<string>",
  "name": "<string>",
  "description": "<string>",
  "balance": 123,
  "dailylimit": 123,
  "transactionlimit": 123,
  "currency": "<string>",
  "requireapprovalforall": true,
  "requireapprovalaboveamount": 123,
  "tags": [
    {}
  ]
}'
{
  "id": "agent_bRSEFnMRD1fvkMM39hzPdM",
  "apikey": "mag_eJwVyN0OgiAYANA3cprT1qV_tY8E0jCVuyILSMtNG-LTt87l6SySt4NQVCGoVvCIggneZSASCOE1NpcE7ZzOopH_Q1c-12A4K4e8zgxnMJM0sjjxFE3xJmc4wDUsre4lGUpJzzDB0Mt7AiFmwiUaAppin1ijeCMN6M9C1mKD12ihTPiPwjkNZXQPme6DbGlNBc9aPfcCbb_dMRb2MbE-vqIKzdgtfgVGPxc",
  "name": "Payment Assistant",
  "description": "Handles payment processing for customer support",
  "status": "active",
  "walletAddress": {
    "addressId": "",
    "networkId": "base-sepolia",
    "walletId": ""
  },
  "balance": "6",
  "currency": "USDC",
  "paymentRules": {
    "dailyLimit": 1000,
    "transactionLimit": 100,
    "requireApprovalAboveAmount": 50,
    "requireApprovalForAll": false
  },
  "tags": [
    "customer-support",
    "payments"
  ],
  "created": "2025-05-03T18:52:39.911685+00:00",
  "transferResult": {
    "success": true,
    "txHash": "0x123...abc",
    "message": "Successfully transferred 6 USDC from user to agent wallet"
  },
  "faucetTransaction": {
    "success": true,
    "txHash": "0xabc...123",
    "message": "ETH testnet funds received via faucet"
  }
}

Multi-step Process: This endpoint creates a new agent, generates a blockchain wallet, and can fund the wallet from your user account or via a testnet faucet.

​
Request Headers

​
x-api-key
string
required

Your API key for authentication

​
Request Body

​
userid
string
required

ID of the user creating the agent

​
walletaddress
string

User’s wallet address for funding (optional)

​
name
string
required

Name of the agent

​
description
string

Purpose and functionality of the agent

​
balance
integer

Initial balance to fund the agent (in smallest units)

​
dailylimit
integer

Maximum amount that can be spent per day

​
transactionlimit
integer

Maximum amount for a single transaction

​
currency
string
default:"USDC"

Currency type to use (defaults to USDC)

​
requireapprovalforall
boolean
default:"false"

Whether all transactions require approval

​
requireapprovalaboveamount
integer

Transactions above this amount require approval

​
tags
array

Categories or labels to assign to the agent

​
Response

​
id
string

Unique agent identifier

​
apikey
string

The API key for the agent

​
name
string

Name of the agent

​
description
string

Purpose and functionality of the agent

​
status
string

Current status of the agent (active, inactive, paused)

​
walletAddress
object
​
balance
string

Current balance of the agent

​
currency
string

Currency type used

​
paymentRules
object
​
tags
array

Categories or labels assigned to the agent

​
created
string

Timestamp when the agent was created

​
transferResult
object
​
faucetTransaction
object
{
  "id": "agent_bRSEFnMRD1fvkMM39hzPdM",
  "apikey": "mag_eJwVyN0OgiAYANA3cprT1qV_tY8E0jCVuyILSMtNG-LTt87l6SySt4NQVCGoVvCIggneZSASCOE1NpcE7ZzOopH_Q1c-12A4K4e8zgxnMJM0sjjxFE3xJmc4wDUsre4lGUpJzzDB0Mt7AiFmwiUaAppin1ijeCMN6M9C1mKD12ihTPiPwjkNZXQPme6DbGlNBc9aPfcCbb_dMRb2MbE-vqIKzdgtfgVGPxc",
  "name": "Payment Assistant",
  "description": "Handles payment processing for customer support",
  "status": "active",
  "walletAddress": {
    "addressId": "",
    "networkId": "base-sepolia",
    "walletId": ""
  },
  "balance": "6",
  "currency": "USDC",
  "paymentRules": {
    "dailyLimit": 1000,
    "transactionLimit": 100,
    "requireApprovalAboveAmount": 50,
    "requireApprovalForAll": false
  },
  "tags": [
    "customer-support",
    "payments"
  ],
  "created": "2025-05-03T18:52:39.911685+00:00",
  "transferResult": {
    "success": true,
    "txHash": "0x123...abc",
    "message": "Successfully transferred 6 USDC from user to agent wallet"
  },
  "faucetTransaction": {
    "success": true,
    "txHash": "0xabc...123",
    "message": "ETH testnet funds received via faucet"
  }
}

​
Status Codes

Status CodeDescription
200Agent created and funded successfully
201Agent created, but funding transfer failed
400Bad Request - Invalid or missing parameters
404Not Found - User ID not found
500Internal Server Error

Important: Store the returned API key securely as it will be needed for all future operations with this agent.