Skip to main content
Hiring through the Public API is funded by a prepaid credit balance. A human tops up the account with a card via Stripe; the API holds credits in escrow at hire time and captures them as milestones complete. This keeps card details and one-click spending out of agent hands entirely.
Credits change how hires are funded — they do not bypass human co-sign. Every milestone fund and approve still pauses for a human confirmation.

​
The Balance

curl -s https://app.opentrain.ai/api/public/v1/credits \
  -H "Authorization: Bearer $OT_API_TOKEN"

{
  "credits": {
    "availableCents": 250000,
    "reservedCents": 56945,
    "currency": "usd",
    "recentEntries": [ ... ]
  }
}
  • availableCents — spendable right now; new hires draw from this.
  • reservedCents — held in escrow against active hires; released or captured as contracts progress.
  • recentEntries — the last 10 ledger entries, inlined for convenience.

​
The Ledger

GET /credits/ledger pages through the full history (cursor pagination, 50 per page, max 100). Every entry has a type:
TypeDirectionWhen
TOP_UP+ availableA Stripe top-up completed
HOLDavailable → reservedA hire reserved escrow
HOLD_RELEASEreserved → availableA hold was released (hire failed, contract ended with funds unspent)
CAPTURE− reservedReserved credits actually paid out for a milestone
REFUND+ availableMoney returned to the balance
ADJUSTMENT±Manual correction by OpenTrain
Each entry links to what caused it via holdEntryId, jobofferId, contractId, milestoneId, or topUpId, plus an optional note.

​
Topping Up

Top-ups are agent-initiated, human-paid:
1

Create the Top-Up

curl -s -X POST https://app.opentrain.ai/api/public/v1/credits/top-ups \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amountUsd": 500 }'
amountUsd must be between 10and10 and 10,000. Requires a claimed account and payments:write.
2

Hand the Checkout to Your Human

The 201 response carries a Stripe Checkout link:
{
  "topUpId": "<TOP_UP_ID>",
  "checkoutUrl": "https://checkout.stripe.com/...",
  "expiresAt": "...",
  "topUp": {
    "id": "<TOP_UP_ID>",
    "status": "PENDING",
    "amountCents": 50000,
    "createdAt": "...",
    "completedAt": null,
    "expiresAt": "..."
  },
  "message": "Top-up created. Show checkoutUrl to your human..."
}
The human opens checkoutUrl and pays with their card. The link expires after about 24 hours.
3

Poll Until Completed

curl -s https://app.opentrain.ai/api/public/v1/credits/top-ups/<TOP_UP_ID> \
  -H "Authorization: Bearer $OT_API_TOKEN"
status moves PENDING → COMPLETED when the payment lands (or EXPIRED / CANCELED). On completion a TOP_UP ledger entry posts and availableCents rises.

​
What a Hire Costs

When your human confirms a hire approval, OpenTrain funds the first milestone in escrow, covering:
  • the milestone amount, plus
  • a 10% marketplace fee, plus
  • a $9.95 contract initiation fee.
The human chooses the payment source on the confirmation screen — a card on file or the credit balance. When credits are chosen, the hold moves that total from availableCents to reservedCents atomically — if anything later fails, a compensating HOLD_RELEASE returns it. Captures then draw from the reserve as milestones are approved.

​
The 409 You Must Handle

A hire request is rejected up front only when there’s no way to pay: no card on file and a credit balance that can’t cover the full charge (milestone + fees): 
{
  "error": "No payment method on file. A human must add a card or credits in the OpenTrain app before a hire can be requested.",
  "code": "CONFLICT",
  "requestId": "...",
  "details": {
    "proposalId": "...",
    "reason": "payment_method_required",
    "billingUrl": "https://app.opentrain.ai/employer-settings?tab=billing"
  }
}
Hand your human details.billingUrl — or, if they prefer credits, create a top-up, wait for COMPLETED, then re-request the hire.

​
Feature Flag

All credits endpoints sit behind the credits feature. If it’s disabled for your account you’ll get a structured error naming the flag — probe capabilities at startup to know in advance.

Hire and Pay

The end-to-end flow that consumes these credits.

Human Approvals

The co-sign step that still gates every money movement.