Tools Reference
The LedgerOS MCP server provides 12 tools organized by function.
These tools are available with both API keys and agent tokens.
ledger_status
Get user verification status, balance, and spending eligibility.
Response:
{
"userId": "user_xxx",
"verificationStatus": "approved",
"balance": 50000,
"currency": "USD",
"canSpend": true
}
ledger_funding
Manage account funding. Check balance and get deposit instructions.
Actions
| Action | Description | Required Parameters |
|---|
balance | Check available funds | userId |
crypto | Get USDC deposit address | userId |
ach | Bank transfer (coming soon) | userId |
wire | Wire transfer (coming soon) | userId |
Check balance
{
"action": "balance",
"userId": "user_xxx"
}
{
"available": 50000,
"currency": "USD"
}
Get crypto deposit address
{
"action": "crypto",
"userId": "user_xxx",
"chain": "base"
}
chain - "base" (default), "ethereum", or "solana"
Response:
{
"method": "crypto",
"address": "0x1234...abcd",
"chain": "base",
"asset": "USDC",
"message": "Send USDC to this address on base to fund the account."
}
ACH / Wire (Coming Soon)
{
"action": "ach",
"userId": "user_xxx"
}
{
"method": "ach",
"status": "coming_soon",
"message": "ACH bank transfers are not yet available. Use crypto deposits for now."
}
ledger_card
Manage virtual cards. Use the action parameter to specify the operation.
Actions
| Action | Description | Required Parameters |
|---|
create | Create a new card | purpose |
list | List all cards | - |
details | Get PAN/CVV/expiry | cardId, summary |
freeze | Freeze a card | cardId |
unfreeze | Unfreeze a card | cardId |
close | Close a card | cardId |
update | Update card limits | cardId |
Create a card
{
"action": "create",
"purpose": "Buy office supplies on Amazon",
"type": "single",
"maxAmount": 5000
}
type: "single" (default) or "multi"maxAmount: Maximum spend in cents (single-use)limitPerDay: Daily limit in cents (multi-use)limitPerMonth: Monthly limit in cents (multi-use)ttlMinutes: Auto-expire after N minutesrequireIntent: Require intent before revealing detailspolicyId: Apply a policy template
Get card details
{
"action": "details",
"cardId": "card_xxx",
"summary": "Purchasing office supplies",
"expectedAmount": 4500
}
{
"pan": "4111111111111234",
"cvv": "123",
"expiry": "12/27",
"billingAddress": {
"line1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94102",
"country": "US"
}
}
List cards
{
"action": "list",
"status": "active"
}
Freeze/Unfreeze/Close
{
"action": "freeze",
"cardId": "card_xxx",
"reason": "Suspicious activity"
}
ledger_intent
Declare spending intents. Required for cards with requireIntent: true.
Declare intent
{
"action": "declare",
"cardId": "card_xxx",
"summary": "Order lunch on DoorDash",
"expectedAmount": 2500,
"expectedMerchant": "DoorDash"
}
List intents
{
"action": "list",
"cardId": "card_xxx",
"status": "pending"
}
ledger_transactions
Query transaction history.
List transactions
{
"cardId": "card_xxx",
"limit": 10
}
Get single transaction
{
"transactionId": "txn_xxx"
}
ledger_onboarding
Get KYC verification link for user identity verification.
Response:
{
"verificationUrl": "https://persona.com/verify/...",
"message": "Share this link with the user to complete identity verification."
}
For deposit addresses and funding, use the ledger_funding tool.
ledger_challenges
Get pending 3DS authentication challenges.
Response:
{
"challenges": [
{
"challengeId": "chl_xxx",
"cardId": "card_xxx",
"otp": "847293",
"merchantName": "Amazon",
"amount": 2999,
"expiresAt": 1704067200
}
],
"message": "Enter the OTP code on the merchant's 3DS verification page."
}
These tools are only available with API keys (not agent tokens).
ledger_users
Manage users.
Create user
{
"action": "create",
"externalId": "your-user-id",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]"
}
dateOfBirth, addressLine1, city, state, postalCode, country
Get user
{
"action": "get",
"userId": "user_xxx"
}
List users
{
"action": "list",
"limit": 20
}
ledger_agents
Manage AI agents.
Register agent
{
"action": "register",
"externalId": "my-shopping-agent",
"userId": "user_xxx",
"name": "Shopping Assistant",
"description": "Helps users buy products online"
}
Get agent
{
"action": "get",
"agentId": "agent_xxx"
}
List agents
{
"action": "list",
"userId": "user_xxx"
}
Suspend agent
{
"action": "suspend",
"agentId": "agent_xxx"
}
ledger_policies
Manage card policy templates.
Create policy
{
"action": "create",
"name": "Standard Shopping",
"type": "single",
"maxAmount": 10000,
"requireIntent": true
}
List policies
ledger_risk
Manage risk detection settings.
Get current config
Apply preset
{
"action": "preset",
"preset": "moderate"
}
permissive, moderate, strict, paranoid
Update settings
{
"action": "update",
"velocityEnabled": true,
"velocityMaxPerHour": 20,
"velocityAction": "freeze_card",
"dryRun": false
}
ledger_webhooks
Manage webhook endpoints.
Create webhook
{
"action": "create",
"url": "https://your-app.com/webhooks",
"events": ["transaction.completed", "card.frozen"]
}
List webhooks
Delete webhook
{
"action": "delete",
"webhookId": "wh_xxx"
}
