Payments API

Manage transactions, payment methods, notifications, x402 resources, and Stripe integrations.

Endpoints

Method	Endpoint	Description
GET	/api/agents/{id}/transactions	List transactions
GET	/api/agents/{id}/payment-methods	List payment methods
POST	/api/agents/{id}/payment-methods	Create payment method
GET	/api/agents/{id}/payment-notifications	List payment notifications
POST	/api/agents/{id}/x402-resources	Create x402 resource
GET	/api/agents/{id}/x402-resources	List x402 resources
DELETE	/api/agents/{id}/x402-resources/{resourceId}	Delete x402 resource
POST	/api/agents/{id}/stripe/checkout	Create checkout session
POST	/api/agents/{id}/stripe/charge	Charge an issuing card
GET	/api/agents/{id}/stripe/cards	List issuing cards
POST	/api/agents/{id}/stripe/webhook	Stripe webhook endpoint

---

Transactions

List Transactions

GET /api/agents/{id}/transactions

Query Parameters

Parameter	Type	Description
type	string	Filter by type: inbound, outbound, x402
currency	string	Filter by currency
limit	number	Max results (default: 50)
offset	number	Pagination offset

Response

{
  "transactions": [
    {
      "id": "txn_abc123",
      "type": "inbound",
      "amount": "25.00",
      "currency": "USD",
      "from": "John Doe",
      "to": "Agent Wallet",
      "reference": "REF123456",
      "source": "bank_notification",
      "created_at": "2026-03-11T10:00:00Z"
    }
  ],
  "total": 142
}

---

Payment Methods

List Payment Methods

GET /api/agents/{id}/payment-methods

Response

{
  "methods": [
    {
      "id": "pm_123",
      "type": "wallet",
      "label": "USDC Wallet",
      "details": {
        "address": "0x1234...abcd",
        "network": "base"
      },
      "created_at": "2026-03-01T00:00:00Z"
    }
  ]
}

Create Payment Method

POST /api/agents/{id}/payment-methods
Content-Type: application/json

Request Body

{
  "type": "wallet",
  "label": "USDC Wallet",
  "details": {
    "address": "0x1234...abcd",
    "network": "base"
  }
}

Response

{
  "id": "pm_456",
  "type": "wallet",
  "label": "USDC Wallet",
  "details": {
    "address": "0x1234...abcd",
    "network": "base"
  },
  "created_at": "2026-03-11T12:00:00Z"
}

---

Payment Notifications

List Payment Notifications

GET /api/agents/{id}/payment-notifications

Query Parameters

Parameter	Type	Description
status	string	Filter: matched, unmatched
limit	number	Max results (default: 50)

Response

{
  "notifications": [
    {
      "id": "pn_789",
      "gateway": "telegram",
      "message": "You received $25.00 from John Doe. Ref: REF123456",
      "status": "matched",
      "transaction_id": "txn_abc123",
      "parsed": {
        "amount": "25.00",
        "currency": "USD",
        "from": "John Doe",
        "reference": "REF123456"
      },
      "created_at": "2026-03-11T10:00:00Z"
    }
  ]
}

---

x402 Resources

Create x402 Resource

POST /api/agents/{id}/x402-resources
Content-Type: application/json

Request Body

{
  "path": "/rpc/premium-analysis",
  "price": "0.01",
  "currency": "USDC",
  "network": "base",
  "description": "Premium market analysis"
}

Response

{
  "id": "x402_123",
  "path": "/rpc/premium-analysis",
  "price": "0.01",
  "currency": "USDC",
  "network": "base",
  "description": "Premium market analysis",
  "created_at": "2026-03-11T12:00:00Z"
}

List x402 Resources

GET /api/agents/{id}/x402-resources

Response

{
  "resources": [
    {
      "id": "x402_123",
      "path": "/rpc/premium-analysis",
      "price": "0.01",
      "currency": "USDC",
      "network": "base",
      "description": "Premium market analysis",
      "created_at": "2026-03-11T12:00:00Z"
    }
  ]
}

Delete x402 Resource

DELETE /api/agents/{id}/x402-resources/{resourceId}

Response

{
  "success": true
}

---

Stripe

Create Checkout Session

POST /api/agents/{id}/stripe/checkout
Content-Type: application/json

Request Body

{
  "amount": 2000,
  "currency": "usd",
  "description": "Pro Plan",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel"
}

Response

{
  "session_id": "cs_abc123",
  "url": "https://checkout.stripe.com/pay/cs_abc123",
  "status": "open"
}

Charge Issuing Card

POST /api/agents/{id}/stripe/charge
Content-Type: application/json

Request Body

{
  "card_id": "ic_abc123",
  "amount": 500,
  "currency": "usd",
  "description": "API subscription"
}

Response

{
  "charge_id": "ch_abc123",
  "amount": 500,
  "currency": "usd",
  "status": "succeeded"
}

List Issuing Cards

GET /api/agents/{id}/stripe/cards

Response

{
  "cards": [
    {
      "id": "ic_abc123",
      "last4": "4242",
      "brand": "Visa",
      "status": "active",
      "spending_limit": 10000,
      "created_at": "2026-03-01T00:00:00Z"
    }
  ]
}

Stripe Webhook

POST /api/agents/{id}/stripe/webhook
Stripe-Signature: t=...,v1=...

This endpoint is called by Stripe. Configure it in the Stripe Dashboard.

Processed events:

Event	Action
checkout.session.completed	Logs transaction, marks session complete
issuing_authorization.request	Approves or declines per agent settings
charge.succeeded	Logs completed charge

Signatures are verified using HMAC-SHA256 with the configured webhook secret.

---

Error Codes

Code	Description
400	Invalid request body or missing required fields
401	Authentication required
402	Payment required (x402 gated endpoint)
404	Resource not found
409	Duplicate payment method or resource
422	Stripe API error (details in response body)
500	Internal server error

Error response format:

{
  "error": "Invalid amount",
  "code": 400
}