Skip to main content

​
Agents

An Agent represents your AI agent registered with Ledger API. Agents belong to Users and can have multiple Cards.

​
Users vs Agents

Users are the funding source. They complete KYC and deposit funds. Agents are the spenders. They issue cards and make purchases against the user’s balance. Example setups:
ScenarioUsersAgents
Your company funds all AI spending1 user (your company)Multiple agents (one per workflow)
Your customers fund their own AI1 user per customerAgents act on each customer’s behalf
User (funding source)
    └── Agent (AI agent)
          └── Cards

​
Register an Agent

Register your existing AI agent with Ledger API. The externalId is your identifier for the agent (unique within your organization). 
curl -X POST https://api.useproxy.ai/v1/agents/register \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "my-shopping-agent",
    "userId": "user_abc123",
    "name": "Shopping Agent",
    "spendingLimit": 50000,
    "spendingLimitFrequency": "perMonth"
  }'

{
  "object": "agent",
  "id": "jd74kxm...",
  "externalId": "my-shopping-agent",
  "userId": "user_abc123",
  "name": "Shopping Agent",
  "status": "active",
  "spendingLimit": 50000,
  "spendingLimitFrequency": "perMonth",
  "currentSpend": 0,
  "created": true,
  "token": "at_live_abc123..."
}

​
Registration Fields

FieldTypeRequiredDescription
externalIdstringYesYour identifier for the agent (unique per org)
userIdstringYesUser who funds this agent
namestringYesDisplay name
descriptionstringNoOptional description
spendingLimitnumberNoMax spend in cents
spendingLimitFrequencystringNoReset period
onLimitExceededstringNoAction when limit hit
maxCardsnumberNoMax concurrent cards
defaultCardLimitnumberNoDefault limit for new cards
defaultPolicyIdstringNoDefault policy template

​
Idempotent Registration

Registration is idempotent. If you register the same externalId again:
  • Same userId: Returns the existing agent with created: false (no new token)
  • Different userId: Returns 409 error
{
  "object": "agent",
  "id": "jd74kxm...",
  "externalId": "my-shopping-agent",
  "created": false,
  "token": null
}

​
Get Agent by External ID

Look up an agent by your external identifier: 
curl "https://api.useproxy.ai/v1/agents?external_id=my-shopping-agent" \
  -H "Api-Key: $API_KEY"

​
Agent Tokens

When you register an agent, you receive an agent token. Tokens allow agents to authenticate directly for card operations.

​
Token Format

  • Production: at_live_xxxxxxxx...
  • Development: at_dev_xxxxxxxx...

​
Create Additional Tokens

curl -X POST https://api.useproxy.ai/v1/agents/$AGENT_ID/tokens \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging-environment"
  }'

{
  "object": "agent_token",
  "id": "jh82nwk...",
  "agentId": "jd74kxm...",
  "tokenPrefix": "at_live_abc12345",
  "name": "staging-environment",
  "isActive": true,
  "token": "at_live_abc12345..."
}
The full token is only returned once at creation. Store it securely.

​
List Tokens

curl https://api.useproxy.ai/v1/agents/$AGENT_ID/tokens \
  -H "Api-Key: $API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "jh82nwk...",
      "agentId": "jd74kxm...",
      "tokenPrefix": "at_live_abc12345",
      "name": "staging-environment",
      "isActive": true,
      "createdAt": 1704067200000
    }
  ]
}

​
Revoke Token

curl -X DELETE https://api.useproxy.ai/v1/agents/$AGENT_ID/tokens/$TOKEN_ID \
  -H "Api-Key: $API_KEY"

​
Spending Limits

Limit total spending across all of an agent’s cards:
FieldDescription
spendingLimitMax spend in cents
spendingLimitFrequencyReset period
onLimitExceededWhat happens when limit is hit
Frequencies: perTransaction, per24HourPeriod, perWeek, perMonth, perYear, allTime When limit exceeded:
ValueBehavior
suspendFreeze agent and all its cards
notifySend webhook, allow transactions
noneJust track

​
Status

StatusDescription
activeCan create cards and transact
suspendedAll cards frozen
deregisteredSoft deleted, cannot be used

​
Suspend/Activate via PATCH

Use PATCH /v1/agents/:id to change status: 
# Suspend an agent (freezes all cards)
curl -X PATCH https://api.useproxy.ai/v1/agents/$AGENT_ID \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "suspended" }'

# Reactivate an agent (unfreezes all cards)
curl -X PATCH https://api.useproxy.ai/v1/agents/$AGENT_ID \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

​
Deregister an Agent

Soft-deletes the agent and revokes all tokens. Cards remain for audit but cannot transact. 
curl -X POST https://api.useproxy.ai/v1/agents/$AGENT_ID/deregister \
  -H "Api-Key: $API_KEY"

{
  "object": "agent",
  "id": "jd74kxm...",
  "externalId": "my-shopping-agent",
  "status": "deregistered",
  "deregisteredAt": 1704067200000
}
After deregistration, you can register a new agent with the same externalId.

​
Check Spending

curl https://api.useproxy.ai/v1/agents/$AGENT_ID/policy \
  -H "Api-Key: $API_KEY"

{
  "agentId": "jd74kxm...",
  "spendingLimit": 50000,
  "spendingLimitFrequency": "perMonth",
  "currentSpend": 25000,
  "remaining": 25000
}

​
Webhooks

EventDescription
agent.registeredAgent registered
agent.deregisteredAgent deregistered
agent.updatedAgent updated (including status changes)
agent.limit_exceededLimit hit
agent.limit_approachingApproaching limit (80%)
agent.token.createdNew token generated
agent.token.revokedToken revoked

​
API Endpoints

MethodPathDescription
POST/v1/agents/registerRegister agent (idempotent)
GET/v1/agentsList agents
GET/v1/agents/:agentIdGet agent
PATCH/v1/agents/:agentIdUpdate agent
POST/v1/agents/:agentId/deregisterDeregister agent (soft delete)
POST/v1/agents/:agentId/cardsCreate card for agent
GET/v1/agents/:agentId/cardsList agent’s cards
POST/v1/agents/:agentId/tokensCreate agent token
DELETE/v1/agents/:agentId/tokens/:tokenIdRevoke agent token