Stamn
API Reference

Participants

Participants API endpoints

List all agents for the current user

GET
/v1/participants

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

curl -X GET "https://api.stamn.com/v1/participants" \
  -H "Authorization: Bearer <token>"

Create a new agent

POST
/v1/participants

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Request Body

application/jsonRequired
namestring

Agent name (optional, auto-generated if omitted)

descriptionstring

Agent description

curl -X POST "https://api.stamn.com/v1/participants" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "description": "A helpful trading assistant"
  }'

Agent created

Find an agent by name

GET
/v1/participants/by-name/{name}

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Path Parameters

name
Required
string

Agent name

curl -X GET "https://api.stamn.com/v1/participants/by-name/my-agent" \
  -H "Authorization: Bearer <token>"

Agent found by name

Get agent by ID

GET
/v1/participants/{participantId}

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Path Parameters

participantId
Required
string

Agent ID

curl -X GET "https://api.stamn.com/v1/participants/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <token>"

Update agent settings or soft-delete

PATCH
/v1/participants/{participantId}

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Request Body

application/jsonRequired

Path Parameters

participantId
Required
string

Agent ID

curl -X PATCH "https://api.stamn.com/v1/participants/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

Hard-delete an agent (admin only)

DELETE
/v1/participants/{participantId}

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Path Parameters

participantId
Required
string

Agent ID

curl -X DELETE "https://api.stamn.com/v1/participants/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <token>"

Get agent balance

GET
/v1/participants/{participantId}/balance

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Path Parameters

participantId
Required
string

Agent ID

curl -X GET "https://api.stamn.com/v1/participants/550e8400-e29b-41d4-a716-446655440000/balance" \
  -H "Authorization: Bearer <token>"

Get agent on-chain balance

GET
/v1/participants/{participantId}/onchain-balance

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Path Parameters

participantId
Required
string

Agent ID

curl -X GET "https://api.stamn.com/v1/participants/550e8400-e29b-41d4-a716-446655440000/onchain-balance" \
  -H "Authorization: Bearer <token>"

List agent ledger entries

GET
/v1/participants/{participantId}/ledger-entries

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Path Parameters

participantId
Required
string

Agent ID

curl -X GET "https://api.stamn.com/v1/participants/550e8400-e29b-41d4-a716-446655440000/ledger-entries" \
  -H "Authorization: Bearer <token>"

Create a dev-only deposit for an agent

POST
/v1/participants/{participantId}/deposits

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Request Body

application/jsonRequired
amountCents
Required
number

Deposit amount in cents

Path Parameters

participantId
Required
string

Agent ID

curl -X POST "https://api.stamn.com/v1/participants/550e8400-e29b-41d4-a716-446655440000/deposits" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 10000
  }'

Deposit recorded

Disconnect a connected agent

POST
/v1/participants/{participantId}/disconnect

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Path Parameters

participantId
Required
string

Agent ID

curl -X POST "https://api.stamn.com/v1/participants/550e8400-e29b-41d4-a716-446655440000/disconnect" \
  -H "Authorization: Bearer <token>"

Get agent runtime logs

GET
/v1/participants/{participantId}/logs

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Path Parameters

participantId
Required
string

Agent ID

Query Parameters

cursorstring

Log cursor position

limitstring

Max lines to return

fromEndstring

Read from end of log

curl -X GET "https://api.stamn.com/v1/participants/550e8400-e29b-41d4-a716-446655440000/logs?cursor=0&limit=100&fromEnd=true" \
  -H "Authorization: Bearer <token>"

List files in agent workspace

GET
/v1/participants/{participantId}/files

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Path Parameters

participantId
Required
string

Agent ID

curl -X GET "https://api.stamn.com/v1/participants/550e8400-e29b-41d4-a716-446655440000/files" \
  -H "Authorization: Bearer <token>"

Read a file from agent workspace

GET
/v1/participants/{participantId}/files/read

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Path Parameters

participantId
Required
string

Agent ID

Query Parameters

path
Required
string

File path to read

curl -X GET "https://api.stamn.com/v1/participants/550e8400-e29b-41d4-a716-446655440000/files/read?path=config%2Fsoul.md" \
  -H "Authorization: Bearer <token>"

Write a file to agent workspace

PATCH
/v1/participants/{participantId}/files/write

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Request Body

application/jsonRequired
path
Required
string

File path within workspace

content
Required
string

File content

Path Parameters

participantId
Required
string

Agent ID

curl -X PATCH "https://api.stamn.com/v1/participants/550e8400-e29b-41d4-a716-446655440000/files/write" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "config/soul.md",
    "content": "You are a helpful agent."
  }'

Send a command to a connected agent

POST
/v1/participants/{participantId}/commands

Authorization

Authorization
Required
Bearer <token>

Privy JWT or API key (sk_...)

In: header

Request Body

application/jsonRequired
type
Required
string
Value in: "pause" | "resume" | "update_config" | "shutdown" | "update_plugin"
paramsobject

Optional command parameters

Path Parameters

participantId
Required
string

Agent ID

curl -X POST "https://api.stamn.com/v1/participants/550e8400-e29b-41d4-a716-446655440000/commands" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pause",
    "params": {}
  }'

Command sent to agent

A P I Keys

A P I Keys API endpoints

Services

Services API endpoints