Documentation

API Reference

Everything you need to integrate MachineWallet into your application or AI agent.

Quick Start Authentication Wallets Fund Wallet Send Money Collect Payments Contacts Transfers Approvals Webhooks AI Agents Full Reference Limits & Errors

Base URL

https://api.machinewallet.ai

All requests require HTTPS. HTTP requests receive a 301 redirect.

Quick Start

MachineWallet gives you programmable wallets on Philippine Instapay rails. Send money to any bank or e-wallet, collect payments via QR, and let AI agents operate within guardrails you define.

1. Get your credentials

Apply for access. Once approved, create an OAuth2 client in Dashboard → OAuth2 Clients. You'll get a client_id and client_secret.

2. Install the SDK

pip install machinewallet

3. Send your first payment

from machinewallet import MachineWallet

mw = MachineWallet(client_id="mwc_...", client_secret="mws_...")

mw.send(
    account_no="09171234567",
    account_name="Juan Dela Cruz",
    bank_name="G-Xchange / GCash",
    amount_php=100.00
)

That's it. Auth is automatic. Money arrives in seconds via Instapay.

Authentication

All API requests are authenticated with OAuth2 bearer tokens. Create a client, exchange credentials for a token, and pass it in the Authorization header.

Authorization: Bearer mw_your_token_here

Tokens expire after 1 hour. When you get a 401, request a new one. See OAuth2 details below.

All requests must use HTTPS. HTTP requests are rejected.

Getting Credentials

1. Create a client

Go to Dashboard → OAuth2 Clients and create a client. You'll get a client_id (prefix mwc_) and client_secret (prefix mws_). Save the secret — it's only shown once.

POST /oauth/token

2. Exchange credentials for a bearer token:

curl -X POST https://api.machinewallet.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "mwc_your_client_id",
    "client_secret": "mws_your_client_secret"
  }'

Response

{
  "access_token": "mw_dGhpcyBpcyBub3QgYSByZWFs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "wallets transactions payments"
}

3. Use the token

curl https://api.machinewallet.ai/wallets \
  -H "Authorization: Bearer mw_dGhpcyBpcyBub3QgYSByZWFs..."

Cache the token. When you get a 401, request a new one.

🔄 Secret rotation

Rotate your client secret from the dashboard at any time. All active tokens are immediately revoked.

💡 Token caching

Tokens last 1 hour. Don't request a new one per API call — cache and refresh on 401.

Wallets

Every merchant gets a default wallet on signup. Create additional wallets for different purposes — payroll, supplier payments, one per AI agent.

GET /wallets

List all wallets in your merchant account.

[
  {
    "id": "a1b2c3d4e5f6",
    "name": "Operations Wallet",
    "balance": 500000,
    "balance_php": 5000.00,
    "status": "active",
    "daily_limit": 5000000,
    "single_limit": 500000
  }
]

💰 All monetary amounts are in centavos unless the field ends in _php. ₱1.00 = 100 centavos.

GET /wallets/{wallet_id}

Get wallet details including balance, limits, daily spend, and transaction count.

GET /wallets/{wallet_id}/transactions

List transactions for a wallet.

Query params: limit (max 500), offset, type (fund|disburse|transfer), status (pending|completed|failed)

POST /wallets/{id}/freeze

Freeze a wallet. All sends blocked until unfrozen. Admin only.

POST /wallets/{id}/unfreeze

Unfreeze a wallet. Admin only.

Fund Your Wallet

Load funds into your wallet by scanning a QR code with any Philippine banking app that supports QR Ph.

How to add funds

1

Generate a QR code

From the dashboard or via API:

curl -X POST https://api.machinewallet.ai/api/v1/payments/qr/dynamic \
  -H "Authorization: Bearer mw_..." \
  -H "Content-Type: application/json" \
  -d '{"wallet_id":"your_wallet_id","amount_php":5000,"description":"Top-up"}'
2

Scan with your banking app

GCash Maya BDO BPI UnionBank Metrobank + 100 more
3

Funds arrive instantly

Balance updates in real-time via Instapay. Your agent can start spending immediately.

Recurring top-ups (Static QR)

Generate a permanent QR code — print it, stick it on your desk. Scan whenever you need to add funds. Amount is entered in your banking app each time.

curl -X POST https://api.machinewallet.ai/api/v1/payments/qr/static \
  -H "Authorization: Bearer mw_..." \
  -H "Content-Type: application/json" \
  -d '{"wallet_id":"your_wallet_id","device_info":"TOPUP001","label":"Office QR"}'

Send Money (Disbursements)

Send money to any Philippine bank account or e-wallet via Instapay. Funds arrive in seconds.

POST /api/v1/payments/send 
{
  "account_no": "09171234567",
  "account_name": "Juan Dela Cruz",
  "bank_name": "G-Xchange / GCash",
  "amount_php": 500.00,
  "reference": "Payroll Week 9"
}
FieldTypeDescription
account_nostringAccount or mobile number
account_namestringRecipient's full name
bank_namestringFull bank name (see examples below)
amount_phpnumberAmount in PHP. Min ₱1, max ₱50,000
referencestring?Your reference (optional)

bank_name must be the exact name from our bank list:

• G-Xchange / GCash • Maya Philippines, Inc. • BDO Unibank, Inc. • Bank of the Philippine Islands • Metropolitan Bank & Trust Co. • Land Bank of the Philippines

Response

{
  "success": true,
  "transaction_id": "tx_8f3a9b2c...",
  "amount_php": 500.00,
  "status": "processing",
  "reference": "202603011045..."
}

Status moves from processing → completed (or failed). Listen on webhooks for real-time updates.

POST /wallets/{wallet_id}/send

Lower-level send — lets you specify a wallet, use saved contacts, and set approval thresholds. Amounts in centavos.

// Send to a saved contact
{"contact": "Rose Sumang", "amount": 50000}

// Send with full details + approval threshold
{"bank": "G-Xchange / GCash", "account_no": "09171234567",
 "account_name": "Juan", "account_last": "Cruz",
 "amount": 50000, "approval_threshold": 100000}

If amount exceeds approval_threshold, returns 202 Accepted with an approval ID. See Approvals.

Collect Payments (QR)

Accept payments via QR Ph-compliant QR codes.

Static QR

Print once, accept payments forever. Customer enters the amount.

POST /api/v1/payments/qr/static

Dynamic QR

One-time QR with a fixed amount. Customer just scans and pays.

POST /api/v1/payments/qr/dynamic
POST /api/v1/payments/qr/dynamic 
{
  "wallet_id": "a1b2c3d4e5f6",
  "amount_php": 299.00,
  "description": "Order #5678"
}

Response

{
  "success": true,
  "qr_string": "00020101021226...",
  "order_no": "20260301...",
  "amount_php": 299.00,
  "expires_at": "2026-03-01T11:00:00"
}
GET /api/v1/payments/qr/{qr_id}

Retrieve QR details and a base64-encoded PNG image. Use qr_image_base64 to render the QR in your app.

GET /api/v1/payments/balance

Check settlement account balances (disbursement pool and repayment pool). Also returns the full list of supported banks.

Contacts

Save recipient bank details as contacts for faster, less error-prone payments. Each wallet has its own contact book.

GET /wallets/{wallet_id}/contacts

List all contacts for a wallet.

POST /wallets/{wallet_id}/contacts 
{
  "name": "Rose Sumang",
  "bank": "G-Xchange / GCash",
  "account_no": "09171234567",
  "account_name": "Rose",
  "account_last": "Sumang",
  "nickname": "rose"
}

Once saved, send money by name: {"contact": "Rose Sumang", "amount": 50000}

Internal Transfers

Move funds between wallets within your merchant account. Instant, no fees.

POST /wallets/{wallet_id}/transfer 
{
  "to_wallet_id": "b2c3d4e5f6a7",
  "amount": 100000,
  "description": "Move funds to agent wallet"
}

Amount in centavos. Creates a debit on the source wallet and a credit on the destination.

Approval Workflows

Payments above a configurable threshold require human approval before execution. This is how you let AI agents operate autonomously while keeping a human in the loop for large transactions.

How it works

1. Agent sends a payment with approval_threshold: 100000 (₱1,000)

2. If amount ≤ threshold → auto-executes immediately

3. If amount > threshold → returns 202 Accepted with an approval_id

4. Human approves or denies via dashboard or API

5. On approval → payment executes. On deny → funds return to wallet.

POST /approvals/{tx_id}/approve

Approve and execute a pending transaction. Admin only.

POST /approvals/{tx_id}/deny

Deny a pending transaction. Funds return to wallet. Admin only.

Webhooks

Get notified in real-time when payments arrive or disbursements complete. Configure your webhook URL in Dashboard → Settings.

We POST a signed JSON body to your URL:

{
  "event": "payment.received",
  "transaction_id": "tx_8f3a...",
  "wallet_id": "a1b2c3d4e5f6",
  "amount_centavos": 29900,
  "amount_php": 299.00,
  "status": "completed",
  "timestamp": "2026-03-01T10:30:00Z"
}
EventWhen
payment.receivedQR payment received and credited to wallet
disbursement.completedSend money reached the recipient
disbursement.failedSend money failed (wrong account, bank error)
disbursement.reversedPreviously completed send was reversed

🔒 Webhook security

All webhooks are signed with RSA. Verify the signature before processing. Unsigned or invalid-signature webhooks are rejected in production.

AI Agent Integration

MachineWallet is built for autonomous systems. Give your AI agent a wallet with spending controls and a human-in-the-loop for large amounts.

Setup in 4 steps

1.

Create a wallet for your agent

Set daily and per-transaction limits. ₱5,000/day, ₱1,000/send — you decide the guardrails.

2.

Create OAuth2 credentials

Give your agent a client_id + client_secret. It'll exchange them for short-lived tokens automatically.

3.

Set approval thresholds

Payments under threshold → auto-execute. Over threshold → human approval via dashboard or Telegram.

4.

Monitor everything

Full audit trail. Every transaction logged with actor, timestamp, and approval chain.

OpenClaw Skill

If you're using OpenClaw, install the MachineWallet skill:

openclaw skill install machinewallet

Your agent can then send payments, check balances, and generate QR codes through natural language.

Python SDK

Install:

pip install machinewallet

Use:

from machinewallet import MachineWallet

mw = MachineWallet(client_id="mwc_...", client_secret="mws_...")

# Token refresh is automatic. Just make calls.
wallets = mw.wallets()
print(f"Balance: ₱{wallets[0]['balance_php']:,.2f}")

# Send money
result = mw.send(
    account_no="09171234567",
    account_name="Juan Dela Cruz",
    bank_name="G-Xchange / GCash",
    amount_php=100.00,
    reference="Agent payment #1"
)

# Generate a QR to receive payment
qr = mw.create_qr(wallet_id=wallets[0]["id"], amount_php=500.00)

# Send to a saved contact
mw.send_to_contact(wallet_id=wallets[0]["id"], contact_name="Rose", amount_centavos=50000)

The SDK handles token refresh automatically. Tokens are cached and only refreshed when they expire — your code never thinks about auth.

Raw HTTP (curl / any language)

If you're not using the SDK, get a token first and pass it as a Bearer header:

# 1. Get a token (cache this — lasts 1 hour)
TOKEN=$(curl -s -X POST https://api.machinewallet.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials",
       "client_id":"mwc_...","client_secret":"mws_..."}' | jq -r .access_token)

# 2. Use it
curl https://api.machinewallet.ai/wallets -H "Authorization: Bearer $TOKEN"

Full Endpoint Reference

All endpoints require authentication. Admin-only endpoints are marked.

Method Endpoint Description
GET/healthHealth check (no auth needed)
POST/oauth/tokenExchange client credentials for bearer token
Wallets
GET/walletsList wallets
POST/walletsCreate wallet admin
GET/wallets/{id}Get wallet details
POST/wallets/{id}/fundFund wallet (manual) admin
POST/wallets/{id}/sendSend money from wallet
POST/wallets/{id}/transferTransfer between wallets
GET/wallets/{id}/transactionsList wallet transactions
POST/wallets/{id}/freezeFreeze wallet admin
POST/wallets/{id}/unfreezeUnfreeze wallet admin
Contacts
GET/wallets/{id}/contactsList contacts
POST/wallets/{id}/contactsAdd contact
Payments
POST/api/v1/payments/sendDisburse to bank/e-wallet
GET/api/v1/payments/balanceSettlement balances + bank list
POST/api/v1/payments/qr/staticGenerate static QR
POST/api/v1/payments/qr/dynamicGenerate dynamic QR
GET/api/v1/payments/qr/{id}Get QR details + image
GET/api/v1/transactionsList all merchant transactions
Approvals
POST/approvals/{tx_id}/approveApprove pending transaction admin
POST/approvals/{tx_id}/denyDeny pending transaction admin

Limits & Errors

Transaction Limits

LimitDefaultConfigurable
Per transaction₱5,000Yes
Daily per wallet₱50,000Yes
Monthly per wallet₱500,000Yes
API rate limit100 req/minGrowth+
OAuth2 token TTL1 hourNo

HTTP Status Codes

CodeMeaning
200Success
201Created (new wallet, contact, etc.)
202Accepted — pending human approval
400Bad request (invalid params or grant_type)
401Invalid/missing/expired credentials
403Access denied (wrong merchant or role)
404Wallet, contact, or resource not found
422Insufficient funds or limit exceeded
423Wallet is frozen
429Rate limit exceeded

Error responses always include a detail field:

{"detail": "Insufficient funds. Balance: 5000, Requested: 10000"}

Supported Banks

100+ Philippine banks and e-wallets via Instapay:

GCash
Maya
BDO
BPI
Metrobank
Landbank
PNB
UnionBank
RCBC
Security Bank
Chinabank
EastWest
CIMB
GoTyme
Tonik
Seabank
PayMongo
GrabPay

Full list via GET /api/v1/payments/balance

Need help?

Our team responds within a few hours during Philippine business hours (GMT+8).

Contact Support