API Reference

About Motivation Money

Motivation Money is the financial operations layer for AI-native companies using stablecoins. It provides a self-custody treasury model with CEX-routed payouts, delivering both privacy and compliance for global compensation workflows.

The API exposes every operation available in the dashboard — payroll runs, employee management, client and invoice management, treasury visibility, webhooks, and audit logs — designed for both human developers and AI agents.

Base URL

https://app.motivation.money/api/v1

Authentication

All API requests require a bearer token in the Authorization header:

Authorization: Bearer mpk_live_<key>

API keys are created from the Motivation Money dashboard under Settings > API Keys. Each key has:

Name — a label for your reference
Scopes — permissions that control what the key can access
Expiration — optional expiry date
The full key is shown only once at creation. Store it securely.

Scopes

Every API key is issued with a set of scopes that control access. Scopes follow the format resource:action:

Scope	Description
`payroll:read`	List and view payroll runs and payouts
`payroll:write`	Create payroll runs, add adjustments
`payroll:execute`	Confirm, execute, cancel, retry runs and payouts
`employees:read`	List and view employees
`employees:write`	Add, update, deactivate employees
`treasury:read`	View Safe and CEX balances, fund transfers
`treasury:write`	Create fund transfers (Safe to CEX)
`clients:read`	List and view client records
`clients:write`	Create, update, archive clients
`invoices:read`	List and view invoices
`invoices:write`	Create, send, void invoices
`audit:read`	Query audit log entries
`webhooks:manage`	Create, list, delete webhook subscriptions
`settings:read`	View organization settings
`settings:write`	Update organization settings
`jobs:read`	Check async job status

Wildcard scopes are supported: payroll:* grants all payroll actions, and * grants full access.

Rate Limiting

The API enforces a sliding-window rate limit of 100 requests per 60 seconds per API key.

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Idempotency

All POST requests that create resources require an Idempotency-Key header containing a UUID v4:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

If you retry a request with the same idempotency key, the API returns the original response without creating a duplicate.

Response Format

Success responses follow this structure:

{
  "data": { ... },
  "meta": { ... }
}

Paginated responses include pagination metadata:

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 150,
    "total_pages": 6
  }
}

Error responses return:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description",
    "details": null
  }
}

Common Error Codes

Status	Code	Description
400	`bad_request`	Invalid request body or parameters
401	`unauthorized`	Missing or invalid API key
403	`forbidden`	API key lacks required scope
404	`not_found`	Resource does not exist
409	`conflict`	Resource state conflict (e.g., confirming an already-confirmed run)
422	`unprocessable_entity`	Valid request but cannot be processed
429	`rate_limit_exceeded`	Too many requests
500	`internal_error`	Server error

Conventions

Monetary amounts are integers in USD cents. 850000 = $8,500.00.
Timestamps are ISO 8601 in UTC. 2026-03-14T10:30:00Z.
Long-running operations (like payout execution) return 202 Accepted.

OpenAPI Specification

A machine-readable OpenAPI 3.1.0 spec is available at:

GET /api/v1/openapi.json

Use this to generate client SDKs, configure AI agent tool schemas, or import into API testing tools. The interactive API reference pages below are auto-generated from this spec.

Endpoints

Payroll Runs — create, confirm, execute, sync, archive, and manage payroll runs
Payouts — view, retry, and cancel individual payouts
Employees — add, update, list, deactivate, and check email availability
Clients — create, update, archive, and manage client records for invoicing
Invoices — create, send, void, and track invoices with stablecoin payments
Treasury — query Safe and CEX balances, create and track fund transfers
Ad-Hoc Payments — one-off payments outside regular payroll
Jobs — track async long-running operations
Audit Log — query the full action history
Settings — view organization configuration
Webhooks — subscribe to real-time events
Agent Sessions — delegated authority for AI agents

On this page