Actions and approvals for safe financial operations

Actions are Yoshi’s safety layer for operations that modify financial data. Instead of executing immediately, mutating operations create a pending action that must be approved before taking effect.

Why actions exist

Financial operations — placing trades, creating accounts, transferring funds — carry real consequences. The action model ensures:

Every mutating operation requires explicit approval
You can review what will happen before it executes
Actions are auditable with full history
Integrations can propose operations that a human approves

The action lifecycle

  create       approve        execute
    │             │              │
    ▼             ▼              ▼
 pending ──→ approved ──→ executed
    │
    └──→ rejected
    │
    └──→ expired (if expires_at passes)

Status	Description
`pending`	Action created, waiting for approval
`approved`	User approved the action
`rejected`	User rejected the action
`executed`	Action was approved and successfully executed
`expired`	Action expired before a decision was made

Create an action

Actions are created automatically when you call mutating endpoints like paper trading. You can also create custom actions:

import Yoshi from "@yoshi-ai/sdk";

const yoshi = new Yoshi();

const action = await yoshi.actions.create({
  action_type: "paper_trade",
  title: "Buy 10 shares of AAPL",
  description: "Paper trade in Tech Portfolio account",
  proposal_data: {
    symbol: "AAPL",
    side: "buy",
    quantity: 10,
  },
  source: "consumer_api",
});

console.log("Action ID:", action.id);
console.log("Approve at:", action.approval_url);

from yoshi import Yoshi

yoshi = Yoshi()

action = yoshi.actions.create(
    action_type="paper_trade",
    title="Buy 10 shares of AAPL",
    description="Paper trade in Tech Portfolio account",
    proposal_data={
        "symbol": "AAPL",
        "side": "buy",
        "quantity": 10,
    },
    source="consumer_api",
)

print(f"Action ID: {action.id}")
print(f"Approve at: {action.approval_url}")

Check action status

Poll the action to check whether it’s been approved:

const action = await yoshi.actions.retrieve("act_abc123");
console.log("Status:", action.status);

if (action.status === "executed") {
  console.log("Result:", action.execution_result);
}

action = yoshi.actions.retrieve("act_abc123")
print(f"Status: {action.status}")

if action.status == "executed":
    print(f"Result: {action.execution_result}")

List and filter actions

View all actions with optional filters:

// List pending actions
for await (const action of yoshi.actions.list({ status: "pending" })) {
  console.log(`${action.title} — ${action.status}`);
}

// List by type
for await (const action of yoshi.actions.list({
  action_type: "paper_trade",
})) {
  console.log(`${action.title} — ${action.status}`);
}

for action in yoshi.actions.list(status="pending"):
    print(f"{action.title} — {action.status}")

Approve or reject

Submit an approval decision programmatically:

const result = await fetch(
  "https://api.yoshi.ai/actions/act_abc123/decide",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.YOSHI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ decision: "approved" }),
  },
);
const { data } = await result.json();
console.log("Decision:", data.decision, "Status:", data.status);

response = httpx.post(
    "https://api.yoshi.ai/actions/act_abc123/decide",
    headers={"Authorization": f"Bearer {os.environ['YOSHI_API_KEY']}"},
    json={"decision": "approved"},
)
data = response.json()["data"]
print(f"Decision: {data['decision']} Status: {data['status']}")

You can also approve from the Yoshi web app using the approval_url returned when the action was created.

Use idempotency keys

Prevent duplicate actions when retrying:

curl -X POST https://api.yoshi.ai/actions \
  -H "Authorization: Bearer yoshi_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buy-aapl-2026-04-10" \
  -d '{"action_type": "paper_trade", "title": "Buy AAPL", ...}'

If a pending action with the same idempotency key already exists, the API returns the existing action instead of creating a duplicate. A 409 Conflict is returned if the key matches but the parameters differ.

Getting Started

Reference

SDKs

Concepts

Webhooks

Use Cases

Tools

Resources

Actions and approvals for safe financial operations

Why actions exist

The action lifecycle

Create an action

Check action status

List and filter actions

Approve or reject

Use idempotency keys

What’s next

Paper trading

Idempotency

​Why actions exist

​The action lifecycle

​Create an action

​Check action status

​List and filter actions

​Approve or reject

​Use idempotency keys

​What’s next

Paper trading

Idempotency

Why actions exist

The action lifecycle

Create an action

Check action status

List and filter actions

Approve or reject

Use idempotency keys

What’s next