Prompt Endpoint

Submit natural language commands to the Bankr AI agent for processing.

Endpoint

POST /agent/prompt

Request

Headers

Header	Value	Required
Content-Type	application/json	Yes
X-API-Key	Your API key	Yes

Body

{
  "prompt": "swap $10 of ETH to USDC on base"
}

Field	Type	Description	Required
prompt	string	Natural language command (max 10,000 characters)	Yes
threadId	string	Continue an existing conversation thread	No
maxMode	object	Use a premium model for this request (see Max Mode below)	No

When threadId is provided, the agent loads prior messages from that thread so it has conversation context. If omitted, a new thread is created automatically.

Response

Success (202 Accepted)

{
  "success": true,
  "jobId": "job_ABC123",
  "threadId": "thr_XYZ789",
  "status": "pending",
  "message": "Prompt submitted successfully. Use the jobId to check status."
}

Field	Type	Description
success	boolean	Whether the request was successful
jobId	string	Unique identifier for tracking this job
threadId	string	Conversation thread ID (reuse to continue the conversation)
status	string	Current status ("pending")
message	string	Human-readable message

Error Responses

Status	error	When
400	Invalid request	prompt missing or not a string, threadId not a string, or maxMode.model is a model Max Mode doesn't offer
400	Prompt too long	prompt is longer than 10,000 characters
401	API key required / Invalid API key	No key sent, or the key is invalid or inactive
403	Agent API access not enabled	The key's Agent API flag is off
403	IP address not allowed	The request IP isn't in the key's IP allowlist
403	subscription_required	The wallet has neither Bankr Club nor Max Mode with a positive LLM credit balance; the body carries a remediation list
403	Account banned	The account is banned from the API
404	Thread not found	threadId doesn't exist or belongs to another wallet
429	Daily limit exceeded	The rolling 24-hour message quota is used up

Each body carries error and a human-readable message; the exact messages are in the OpenAPI spec. The 429 also carries the quota:

{
  "error": "Daily limit exceeded",
  "message": "You have reached your daily API limit of 100 messages. Upgrade to Bankr Club for 1000 messages/day. Resets at 2025-01-15T12:00:00.000Z",
  "resetAt": 1736942400000,
  "limit": 100,
  "used": 100
}

The daily limit is 1,000 messages with Bankr Club and 100 without (a custom limit Bankr sets on a key overrides both), counted over a rolling 24 hours rather than reset at midnight. See API Keys for rate limits, IP allowlisting, and other key permissions.

Examples

Simple Prompt

curl -X POST https://api.bankr.bot/agent/prompt \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"prompt": "swap $50 of ETH to USDC on base"}'

Continue a Conversation

Use the threadId from a previous response to continue the conversation with context:

curl -X POST https://api.bankr.bot/agent/prompt \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"prompt": "and what about SOL?", "threadId": "thr_XYZ789"}'

Max Mode

Max Mode lets you choose a premium LLM model for individual requests. Usage is billed against your LLM credit balance.

Usage

Pass the maxMode object in the request body:

{
  "prompt": "analyze my portfolio and suggest optimizations",
  "maxMode": {
    "enabled": true,
    "model": "claude-opus-5"
  }
}

Field	Type	Description
maxMode.enabled	boolean	Set to true to activate Max Mode
maxMode.model	string	A model ID that Max Mode offers

Max Mode offers the gateway's frontier, flagship and balanced models — see Max Mode or run bankr llm models for the current list and prices. A light model answers 400, and a model ID the gateway doesn't know is ignored, so the prompt runs on the standard model.

CLI

Use the --model (or -m) flag with the agent command:

bankr agent "analyze my portfolio" --model claude-opus-5
bankr agent -m claude-sonnet-5.5 "what are my best yield options?"

note

Max Mode requires LLM credits. Without Bankr Club, a Max Mode prompt needs a positive credit balance or it answers 403 subscription_required; if your balance can't cover a request, the agent asks you to top up instead of answering. Top up credits with bankr llm credits add <amount>.

Next Steps

After submitting a prompt, poll for results using the Job Management endpoints.