REST API

Complete REST API reference for MPPFi - the first neobank infrastructure for AI agents built on Solana blockchain with Machine Payments Protocol integration.

Base URL

https://api.mppfi.xyz/v1

Authentication

All API requests require authentication using API keys. Include your API key in the Authorization header:

Authorization: Bearer mppfi_live_abc123...

API Key Types

Secret keys (mppfi_live_...): Use for server-side applications only
Publishable keys (mppfi_pub_...): Safe for client-side use (limited permissions)
Test keys (mppfi_test_...): For sandbox environment testing

Security Best Practices

Never expose secret keys in client-side code or public repositories
Rotate keys regularly using the dashboard
Use environment variables to store keys
Implement key rotation without downtime using multiple active keys

Rate Limits

Tier

Rate Limit

Burst Limit

Free

100 req/min

120 req/min

Starter

500 req/min

600 req/min

Growth

2,000 req/min

2,500 req/min

Enterprise

Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499
X-RateLimit-Reset: 1711756800

Pagination

List endpoints support cursor-based pagination:

GET /v1/agents?limit=20&cursor=eyJpZCI6IjEyMyJ9

Parameters:

limit (optional): Number of items to return (1-100, default: 20)
cursor (optional): Pagination cursor from previous response

Response:

{
  "data": [...],
  "has_more": true,
  "next_cursor": "eyJpZCI6IjE0MyJ9"
}

Idempotency

POST requests support idempotency keys to prevent duplicate operations:

Idempotency-Key: unique-key-12345

If a request with the same idempotency key is repeated within 24 hours, the API returns the original response without executing the operation again.

Agent Accounts

Create Agent Account

POST /v1/agents

Creates a new AI agent account with on-chain Solana address and USDC balance.

Request Body:

{
  "name": "Order Processing Agent",
  "description": "Handles automated purchase orders",
  "metadata": {
    "environment": "production",
    "version": "2.1.0",
    "owner": "supply-chain-team"
  },
  "initial_balance": "1000.00",
  "policies": [
    {
      "type": "amount_limit",
      "max_transaction": "500.00",
      "max_daily": "5000.00"
    }
  ]
}

Response (201 Created):

{
  "id": "agent_7x8y9z",
  "object": "agent",
  "name": "Order Processing Agent",
  "description": "Handles automated purchase orders",
  "solana_address": "9xKq3...7pRt2",
  "balance": "1000.00",
  "currency": "USDC",
  "status": "active",
  "metadata": {
    "environment": "production",
    "version": "2.1.0",
    "owner": "supply-chain-team"
  },
  "policies": [
    {
      "id": "policy_abc123",
      "type": "amount_limit",
      "max_transaction": "500.00",
      "max_daily": "5000.00",
      "status": "active"
    }
  ],
  "created_at": "2026-03-30T10:15:30Z",
  "updated_at": "2026-03-30T10:15:30Z"
}

Retrieve Agent Account

GET /v1/agents/:id

Response (200 OK):

{
  "id": "agent_7x8y9z",
  "object": "agent",
  "name": "Order Processing Agent",
  "solana_address": "9xKq3...7pRt2",
  "balance": "1000.00",
  "currency": "USDC",
  "status": "active",
  "created_at": "2026-03-30T10:15:30Z"
}

List Agent Accounts

GET /v1/agents

Query Parameters:

limit (optional): Number of results (1-100, default: 20)
cursor (optional): Pagination cursor
status (optional): Filter by status (active, suspended, closed)
created_after (optional): ISO 8601 timestamp
created_before (optional): ISO 8601 timestamp

Response (200 OK):

{
  "object": "list",
  "data": [
    {
      "id": "agent_7x8y9z",
      "name": "Order Processing Agent",
      "balance": "1000.00",
      "status": "active"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6IjE0MyJ9"
}

Update Agent Account

PATCH /v1/agents/:id

Request Body:

{
  "name": "Updated Agent Name",
  "description": "New description",
  "metadata": {
    "version": "2.2.0"
  }
}

Response (200 OK):

{
  "id": "agent_7x8y9z",
  "name": "Updated Agent Name",
  "description": "New description",
  "updated_at": "2026-03-30T11:20:15Z"
}

Suspend Agent Account

POST /v1/agents/:id/suspend

Suspends agent account, preventing all transactions while maintaining on-chain state.

Response (200 OK):

{
  "id": "agent_7x8y9z",
  "status": "suspended",
  "suspended_at": "2026-03-30T12:00:00Z"
}

Reactivate Agent Account

POST /v1/agents/:id/reactivate

Response (200 OK):

{
  "id": "agent_7x8y9z",
  "status": "active",
  "reactivated_at": "2026-03-30T12:30:00Z"
}

Close Agent Account

DELETE /v1/agents/:id

Permanently closes agent account and withdraws remaining balance to specified address.

Request Body:

{
  "withdrawal_address": "5xPq7...3mKt9"
}

Response (200 OK):

{
  "id": "agent_7x8y9z",
  "status": "closed",
  "final_balance": "0.00",
  "withdrawal_transaction": "tx_xyz789",
  "closed_at": "2026-03-30T13:00:00Z"
}

Payments

Create Payment (MPP)

POST /v1/payments

Creates a payment using Machine Payments Protocol, with on-chain settlement via Solana.

Request Body:

{
  "agent_id": "agent_7x8y9z",
  "amount": "150.50",
  "currency": "USDC",
  "merchant_id": "merchant_abc123",
  "description": "API subscription - March 2026",
  "mpp_protocol": {
    "version": "1.0",
    "service_code": "api_access",
    "authorization_method": "cryptographic_signature"
  },
  "metadata": {
    "order_id": "ORD-2026-03-001",
    "customer_id": "cust_456"
  },
  "idempotency_key": "payment_20260330_001"
}

Response (201 Created):

{
  "id": "pay_xyz123",
  "object": "payment",
  "agent_id": "agent_7x8y9z",
  "amount": "150.50",
  "currency": "USDC",
  "merchant_id": "merchant_abc123",
  "merchant_name": "OpenAI API Services",
  "description": "API subscription - March 2026",
  "status": "completed",
  "mpp_protocol": {
    "version": "1.0",
    "service_code": "api_access",
    "authorization_signature": "0x7a8b9c...",
    "proof_url": "https://mpp.protocol/proof/xyz123"
  },
  "blockchain": {
    "network": "solana",
    "transaction_signature": "5xPq7...3mKt9",
    "slot": 245678901,
    "confirmation_status": "finalized",
    "block_time": 1711789530,
    "explorer_url": "https://solscan.io/tx/5xPq7...3mKt9"
  },
  "fees": {
    "mppfi_fee": "0.50",
    "network_fee": "0.000005",
    "total_fee": "0.500005"
  },
  "metadata": {
    "order_id": "ORD-2026-03-001",
    "customer_id": "cust_456"
  },
  "created_at": "2026-03-30T10:30:00Z",
  "completed_at": "2026-03-30T10:30:01Z"
}

Create Direct Transfer

POST /v1/transfers

Creates a direct USDC transfer between Solana addresses.

Request Body:

{
  "agent_id": "agent_7x8y9z",
  "recipient_address": "8yLp2...5nKq7",
  "amount": "250.00",
  "currency": "USDC",
  "description": "Payment to supplier",
  "metadata": {
    "invoice_id": "INV-2026-150"
  }
}

Response (201 Created):

{
  "id": "transfer_def456",
  "object": "transfer",
  "agent_id": "agent_7x8y9z",
  "sender_address": "9xKq3...7pRt2",
  "recipient_address": "8yLp2...5nKq7",
  "amount": "250.00",
  "currency": "USDC",
  "status": "completed",
  "blockchain": {
    "network": "solana",
    "transaction_signature": "4wRs8...2pLm5",
    "confirmation_status": "finalized"
  },
  "created_at": "2026-03-30T11:00:00Z"
}

Retrieve Payment

GET /v1/payments/:id

Response (200 OK):

{
  "id": "pay_xyz123",
  "amount": "150.50",
  "status": "completed",
  "blockchain": {
    "transaction_signature": "5xPq7...3mKt9",
    "confirmation_status": "finalized"
  }
}

List Payments

GET /v1/payments

Query Parameters:

agent_id (optional): Filter by agent
merchant_id (optional): Filter by merchant
status (optional): Filter by status (pending, completed, failed)
amount_min (optional): Minimum amount filter
amount_max (optional): Maximum amount filter
created_after (optional): ISO 8601 timestamp
created_before (optional): ISO 8601 timestamp
limit (optional): Number of results (1-100, default: 20)
cursor (optional): Pagination cursor

Response (200 OK):

{
  "object": "list",
  "data": [
    {
      "id": "pay_xyz123",
      "amount": "150.50",
      "merchant_name": "OpenAI API Services",
      "status": "completed",
      "created_at": "2026-03-30T10:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Cancel Payment

POST /v1/payments/:id/cancel

Cancels a pending payment (only possible before blockchain confirmation).

Response (200 OK):

{
  "id": "pay_xyz123",
  "status": "cancelled",
  "cancelled_at": "2026-03-30T10:31:00Z"
}

Policies

Create Policy

POST /v1/policies

Creates an on-chain policy enforced by Solana smart contracts.

Request Body:

{
  "agent_id": "agent_7x8y9z",
  "name": "Daily Spending Limit",
  "description": "Restrict agent to $5,000 daily spending",
  "rules": [
    {
      "type": "amount_limit",
      "max_transaction": "500.00",
      "max_daily": "5000.00"
    },
    {
      "type": "merchant_allowlist",
      "allowed_merchants": [
        "merchant_abc123",
        "merchant_def456"
      ]
    },
    {
      "type": "time_restriction",
      "allowed_hours": {
        "start": "09:00",
        "end": "17:00",
        "timezone": "UTC"
      },
      "allowed_days": ["monday", "tuesday", "wednesday", "thursday", "friday"]
    }
  ],
  "enforcement": "on_chain",
  "priority": 1
}

Response (201 Created):

{
  "id": "policy_abc123",
  "object": "policy",
  "agent_id": "agent_7x8y9z",
  "name": "Daily Spending Limit",
  "rules": [
    {
      "type": "amount_limit",
      "max_transaction": "500.00",
      "max_daily": "5000.00"
    }
  ],
  "enforcement": "on_chain",
  "status": "active",
  "blockchain": {
    "program_address": "MPPFi...Policy123",
    "deployment_signature": "3xLm5...8qNp2"
  },
  "created_at": "2026-03-30T09:00:00Z"
}

Retrieve Policy

GET /v1/policies/:id

Response (200 OK):

{
  "id": "policy_abc123",
  "name": "Daily Spending Limit",
  "status": "active",
  "rules": [...]
}

List Policies

GET /v1/policies

Query Parameters:

agent_id (optional): Filter by agent
status (optional): Filter by status (active, disabled)
limit (optional): Number of results
cursor (optional): Pagination cursor

Response (200 OK):

{
  "object": "list",
  "data": [
    {
      "id": "policy_abc123",
      "name": "Daily Spending Limit",
      "status": "active"
    }
  ],
  "has_more": false
}

Update Policy

PATCH /v1/policies/:id

Updates policy and deploys changes to Solana smart contract.

Request Body:

{
  "rules": [
    {
      "type": "amount_limit",
      "max_transaction": "1000.00",
      "max_daily": "10000.00"
    }
  ]
}

Response (200 OK):

{
  "id": "policy_abc123",
  "rules": [...],
  "blockchain": {
    "update_signature": "6yPq8...4mKt3"
  },
  "updated_at": "2026-03-30T12:00:00Z"
}

Disable Policy

POST /v1/policies/:id/disable

Response (200 OK):

{
  "id": "policy_abc123",
  "status": "disabled",
  "disabled_at": "2026-03-30T13:00:00Z"
}

Enable Policy

POST /v1/policies/:id/enable

Response (200 OK):

{
  "id": "policy_abc123",
  "status": "active",
  "enabled_at": "2026-03-30T14:00:00Z"
}

Balances

Get Agent Balance

GET /v1/agents/:id/balance

Response (200 OK):

{
  "agent_id": "agent_7x8y9z",
  "available": "1000.00",
  "pending": "50.00",
  "total": "1050.00",
  "currency": "USDC",
  "solana_address": "9xKq3...7pRt2",
  "last_updated": "2026-03-30T15:00:00Z"
}

Get Balance History

GET /v1/agents/:id/balance/history

Query Parameters:

start_date (required): ISO 8601 timestamp
end_date (required): ISO 8601 timestamp
interval (optional): hour, day, week, month (default: day)

Response (200 OK):

{
  "agent_id": "agent_7x8y9z",
  "currency": "USDC",
  "data": [
    {
      "timestamp": "2026-03-30T00:00:00Z",
      "balance": "1000.00"
    },
    {
      "timestamp": "2026-03-31T00:00:00Z",
      "balance": "950.50"
    }
  ]
}

Fund Agent Account

POST /v1/agents/:id/fund

Deposits USDC to agent's Solana address.

Request Body:

{
  "amount": "500.00",
  "currency": "USDC",
  "source": "bank_account_xyz",
  "description": "Monthly funding"
}

Response (201 Created):

{
  "id": "fund_ghi789",
  "object": "funding",
  "agent_id": "agent_7x8y9z",
  "amount": "500.00",
  "status": "completed",
  "blockchain": {
    "transaction_signature": "7zKp9...5nQt8"
  },
  "created_at": "2026-03-30T16:00:00Z"
}

Merchants

List Merchants

GET /v1/merchants

Lists MPP-compatible merchants accepting agent payments.

Query Parameters:

category (optional): Filter by category
mpp_version (optional): Filter by MPP protocol version
limit (optional): Number of results
cursor (optional): Pagination cursor

Response (200 OK):

{
  "object": "list",
  "data": [
    {
      "id": "merchant_abc123",
      "name": "OpenAI API Services",
      "category": "ai_services",
      "mpp_version": "1.0",
      "solana_address": "7xPq5...3mKt9",
      "supported_currencies": ["USDC"],
      "description": "AI model API access"
    }
  ],
  "has_more": true
}

Retrieve Merchant

GET /v1/merchants/:id

Response (200 OK):

{
  "id": "merchant_abc123",
  "name": "OpenAI API Services",
  "category": "ai_services",
  "mpp_version": "1.0",
  "solana_address": "7xPq5...3mKt9",
  "supported_currencies": ["USDC"],
  "service_codes": ["api_access", "training", "fine_tuning"],
  "pricing": {
    "api_access": {
      "base_rate": "0.002",
      "unit": "per_1k_tokens"
    }
  }
}

Webhooks

Create Webhook Endpoint

POST /v1/webhooks

Request Body:

{
  "url": "https://example.com/webhooks/mppfi",
  "description": "Production webhook endpoint",
  "events": [
    "payment.completed",
    "payment.failed",
    "agent.balance.low",
    "policy.violated"
  ],
  "enabled": true
}

Response (201 Created):

{
  "id": "webhook_jkl012",
  "object": "webhook",
  "url": "https://example.com/webhooks/mppfi",
  "events": ["payment.completed", "payment.failed"],
  "signing_secret": "whsec_abc123...",
  "status": "enabled",
  "created_at": "2026-03-30T17:00:00Z"
}

List Webhooks

GET /v1/webhooks

Response (200 OK):

{
  "object": "list",
  "data": [
    {
      "id": "webhook_jkl012",
      "url": "https://example.com/webhooks/mppfi",
      "status": "enabled"
    }
  ]
}

Update Webhook

PATCH /v1/webhooks/:id

Request Body:

{
  "events": ["payment.completed", "policy.violated"],
  "enabled": false
}

Response (200 OK):

{
  "id": "webhook_jkl012",
  "events": ["payment.completed", "policy.violated"],
  "status": "disabled"
}

Delete Webhook

DELETE /v1/webhooks/:id

Response (204 No Content)

Retrieve Webhook Event

GET /v1/webhook_events/:id

Response (200 OK):

{
  "id": "evt_mno345",
  "type": "payment.completed",
  "data": {
    "payment": {
      "id": "pay_xyz123",
      "amount": "150.50"
    }
  },
  "created_at": "2026-03-30T18:00:00Z"
}

Analytics

Get Agent Analytics

GET /v1/agents/:id/analytics

Query Parameters:

start_date (required): ISO 8601 timestamp
end_date (required): ISO 8601 timestamp
metrics (optional): Comma-separated metrics

Response (200 OK):

{
  "agent_id": "agent_7x8y9z",
  "period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "metrics": {
    "total_transactions": 1250,
    "total_volume": "45000.50",
    "average_transaction": "36.00",
    "total_fees": "150.00",
    "policy_violations": 3,
    "success_rate": 0.998
  },
  "by_merchant": [
    {
      "merchant_id": "merchant_abc123",
      "merchant_name": "OpenAI API Services",
      "transaction_count": 500,
      "total_volume": "15000.00"
    }
  ]
}

Get Payment Analytics

GET /v1/analytics/payments

Query Parameters:

start_date (required): ISO 8601 timestamp
end_date (required): ISO 8601 timestamp
group_by (optional): day, week, month

Response (200 OK):

{
  "period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "summary": {
    "total_payments": 5000,
    "total_volume": "250000.00",
    "total_fees": "833.33",
    "average_payment": "50.00"
  },
  "by_day": [
    {
      "date": "2026-03-30",
      "payment_count": 165,
      "volume": "8250.00"
    }
  ]
}

API Keys

Create API Key

POST /v1/api_keys

Request Body:

{
  "name": "Production Server Key",
  "type": "secret",
  "permissions": ["read", "write"],
  "expires_at": "2027-03-30T00:00:00Z"
}

Response (201 Created):

{
  "id": "key_pqr678",
  "name": "Production Server Key",
  "key": "mppfi_live_abc123...",
  "type": "secret",
  "permissions": ["read", "write"],
  "created_at": "2026-03-30T19:00:00Z",
  "expires_at": "2027-03-30T00:00:00Z"
}

List API Keys

GET /v1/api_keys

Response (200 OK):

{
  "object": "list",
  "data": [
    {
      "id": "key_pqr678",
      "name": "Production Server Key",
      "type": "secret",
      "last_used_at": "2026-03-30T18:30:00Z"
    }
  ]
}

Revoke API Key

DELETE /v1/api_keys/:id

Response (204 No Content)

Errors

All errors follow this format:

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "message": "Agent has insufficient balance for this transaction",
    "param": "amount",
    "request_id": "req_abc123"
  }
}

See Error Reference for complete error codes.

Versioning

The API uses versioning through the URL path (/v1/). Breaking changes will result in a new version (/v2/).

Current Version: v1 (Stable)

Version History

v1 (2025-12-01): Initial stable release
- Agent account management
- Machine Payments Protocol integration
- Solana blockchain settlement
- On-chain policy enforcement

SDKs

Official SDKs are available for:

TypeScript/Node.js: npm install @mppfi/node
Python: pip install mppfi
Rust: cargo add mppfi
Go: go get github.com/mppfi/mppfi-go

See SDK Documentation for language-specific guides.

Support

Documentation: https://docs.mppfi.xyz
API Status: https://status.mppfi.xyz
Support Email: [email protected]
Discord Community: https://discord.gg/mppfi

PreviousAuthorization Engine NextSDKs

Last updated 3 hours ago

Was this helpful?

Good afternoon

hashtagBase URL

hashtagAuthentication

hashtagAPI Key Types

hashtagSecurity Best Practices

hashtagRate Limits

hashtagPagination

hashtagIdempotency

hashtagAgent Accounts

hashtagCreate Agent Account

hashtagRetrieve Agent Account

hashtagList Agent Accounts

hashtagUpdate Agent Account

hashtagSuspend Agent Account

hashtagReactivate Agent Account

hashtagClose Agent Account

hashtagPayments

hashtagCreate Payment (MPP)

hashtagCreate Direct Transfer

hashtagRetrieve Payment

hashtagList Payments

hashtagCancel Payment

hashtagPolicies

hashtagCreate Policy

hashtagRetrieve Policy

hashtagList Policies

hashtagUpdate Policy

hashtagDisable Policy

hashtagEnable Policy

hashtagBalances

hashtagGet Agent Balance

hashtagGet Balance History

hashtagFund Agent Account

hashtagMerchants

hashtagList Merchants

hashtagRetrieve Merchant

hashtagWebhooks

hashtagCreate Webhook Endpoint

hashtagList Webhooks

hashtagUpdate Webhook

hashtagDelete Webhook

hashtagRetrieve Webhook Event

hashtagAnalytics

hashtagGet Agent Analytics

hashtagGet Payment Analytics

hashtagAPI Keys

hashtagCreate API Key

hashtagList API Keys

hashtagRevoke API Key

hashtagErrors

hashtagVersioning

hashtagVersion History

hashtagSDKs

hashtagSupport

Base URL

Authentication

API Key Types

Security Best Practices

Rate Limits

Pagination

Idempotency

Agent Accounts

Create Agent Account

Retrieve Agent Account

List Agent Accounts

Update Agent Account

Suspend Agent Account

Reactivate Agent Account

Close Agent Account

Payments

Create Payment (MPP)

Create Direct Transfer

Retrieve Payment

List Payments

Cancel Payment

Policies

Create Policy

Retrieve Policy

List Policies

Update Policy

Disable Policy

Enable Policy

Balances

Get Agent Balance

Get Balance History

Fund Agent Account

Merchants

List Merchants

Retrieve Merchant

Webhooks

Create Webhook Endpoint

List Webhooks

Update Webhook

Delete Webhook

Retrieve Webhook Event

Analytics

Get Agent Analytics

Get Payment Analytics

API Keys

Create API Key

List API Keys

Revoke API Key

Errors

Versioning

Version History

SDKs

Support