API Reference v1

NexusPay Docs

Complete API reference for managed agent wallets, USDC payments, spending policies, and x402 micropayments.

Introduction

NexusPay is a managed payment infrastructure for AI agents. It provides agent wallets backed by real USDC on Base, policy-gated spending, instant P2P transfers between agents, and x402 micropayment paywalls — all via a single REST API.

Every API response follows a consistent envelope:

json

{
  "success": true,
  "data": { ... }
}

// On error:
{
  "success": false,
  "error": "Human-readable message"
}

ℹBase URL: https://nexuspay.app/api. All amounts are denominated in USDC (dollars). The API accepts and returns decimal values — 10.50 means $10.50 USDC.

Authentication

All API requests must include an API key in the X-Api-Key header. Keys are created per-agent and scoped to their associated wallet.

bash

curl https://nexuspay.app/api/wallets \
  -H "X-Api-Key: nxp_live_sk_•••••••••••••••"

Keys are hashed with SHA-256 before storage — NexusPay never holds your plaintext key after creation. Store it immediately on first issue.

⚠API keys grant full access to the associated agent wallet. Never expose them client-side or commit them to source control.

Wallets

Agent wallets hold USDC balances and interact with the Base blockchain via Coinbase CDP. Each wallet has a unique on-chain address, an internal agent ID, and an optional spending policy.

List wallets

GEThttps://nexuspay.app/wallets

Returns all agent wallets with current balances and status.

bash

curl https://nexuspay.app/api/wallets \
  -H "X-Api-Key: nxp_live_sk_•••"

json

{
  "success": true,
  "data": [
    {
      "agentId": "agent-alpha",
      "address": "0x7a3f...8b2c",
      "balanceUsdc": 245.50,
      "status": "ACTIVE",
      "createdAt": "2025-03-01T10:00:00Z"
    }
  ]
}

Create wallet

POSThttps://nexuspay.app/wallets

Creates a new agent wallet backed by a Coinbase CDP wallet on Base.

Parameter	Type	Description
`agentId`REQUIRED	string	Unique identifier for this agent. Lowercase alphanumeric and hyphens.
`initialBalanceUsdc`	number	Optional starting balance to allocate from treasury. Defaults to 0.
`policyId`	string	ID of a spending policy to attach immediately.

bash

curl -X POST https://nexuspay.app/api/wallets \
  -H "X-Api-Key: nxp_live_sk_•••" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-gamma",
    "initialBalanceUsdc": 50.00
  }'

json

{
  "success": true,
  "data": {
    "agentId": "agent-gamma",
    "address": "0x9c1d...3f7a",
    "balanceUsdc": 50.00,
    "status": "ACTIVE",
    "createdAt": "2026-04-01T12:00:00Z"
  }
}

Transactions

On-chain transactions settle USDC on Base via the Coinbase CDP SDK. Every transaction is validated against the agent's active spending policy before settlement. Balances are decremented atomically before on-chain submission — if the chain call fails, the balance is refunded and the transaction is marked FAILED.

List transactions

GEThttps://nexuspay.app/transactions

Returns the transaction history with optional filters.

Parameter	Type	Description
`agentId`	string	Filter by agent. If omitted, returns all transactions.
`status`	CONFIRMED \| PENDING \| FAILED \| REJECTED	Filter by transaction status.
`limit`	number	Max results to return. Defaults to 50.

bash

curl "https://nexuspay.app/api/transactions?agentId=agent-alpha&status=CONFIRMED" \
  -H "X-Api-Key: nxp_live_sk_•••"

Send transaction

POSThttps://nexuspay.app/transactions

Sends USDC from an agent wallet to any Base address. Runs policy checks, decrements balance, submits on-chain, and returns the transaction hash.

Parameter	Type	Description
`fromAgentId`REQUIRED	string	Source agent wallet ID.
`toAddress`REQUIRED	string	Recipient Ethereum address (0x…).
`amountUsdc`REQUIRED	number	Amount in USDC. Must be greater than 0.
`category`	string	Spend category (e.g. compute, storage, api). Used for policy filtering.
`metadata`	object	Arbitrary key-value pairs stored with the transaction.

bash

curl -X POST https://nexuspay.app/api/transactions \
  -H "X-Api-Key: nxp_live_sk_•••" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAgentId": "agent-alpha",
    "toAddress": "0x9b2e...4d1a",
    "amountUsdc": 12.50,
    "category": "compute",
    "metadata": { "jobId": "job_7f3a" }
  }'

json

{
  "success": true,
  "data": {
    "id": "tx_AbCdEfGhI",
    "fromAgentId": "agent-alpha",
    "toAddress": "0x9b2e...4d1a",
    "amountUsdc": 12.50,
    "status": "CONFIRMED",
    "txHash": "0x8f2a...c91e",
    "category": "compute",
    "createdAt": "2026-04-01T12:01:00Z"
  }
}

⚠If the agent's spending policy blocks the transaction, the API returns HTTP 403 with policy_rejected and a breakdown of which checks failed — no funds are moved.

P2P Transfers

Agent-to-agent transfers swap balances within NexusPay's internal ledger — no gas fees, no on-chain latency. Both wallets update atomically in a single database transaction. P2P transfers are still subject to the sender's spending policy.

Transfer between agents

POSThttps://nexuspay.app/p2p

Parameter	Type	Description
`fromAgentId`REQUIRED	string	Sender agent ID.
`toAgentId`REQUIRED	string	Recipient agent ID. Must be an existing active wallet.
`amountUsdc`REQUIRED	number	Amount to transfer in USDC.
`memo`	string	Optional note stored with the transfer (e.g. 'Tool access fee').

bash

curl -X POST https://nexuspay.app/api/p2p \
  -H "X-Api-Key: nxp_live_sk_•••" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAgentId": "agent-alpha",
    "toAgentId": "agent-beta",
    "amountUsdc": 5.00,
    "memo": "Tool access fee"
  }'

json

{
  "success": true,
  "data": {
    "id": "tx_P2pXyZ123",
    "fromAgentId": "agent-alpha",
    "toAgentId": "agent-beta",
    "amountUsdc": 5.00,
    "isP2P": true,
    "status": "CONFIRMED",
    "memo": "Tool access fee",
    "createdAt": "2026-04-01T12:05:00Z"
  }
}

Spending Policies

Policies define the spend rules for an agent wallet. Every outgoing transaction (including P2P) is validated against the agent's active policy. A transaction is rejected if any enabled check fails — the API returns exactly which check blocked it.

maxPerTransaction

Maximum USDC per single transaction

dailyLimit

Aggregate spend cap per calendar day

monthlyLimit

Aggregate spend cap per calendar month

allowedCategories

Whitelist of permitted spend categories

blockedMerchants

Blocklist of recipient addresses

allowedRecipients

Explicit allowlist of recipient addresses

requireApproval

Flag all transactions for manual review

List policies

GEThttps://nexuspay.app/policies

bash

curl https://nexuspay.app/api/policies \
  -H "X-Api-Key: nxp_live_sk_•••"

Create policy

POSThttps://nexuspay.app/policies

Parameter	Type	Description
`agentId`REQUIRED	string	Agent wallet to attach this policy to.
`tier`	CONSERVATIVE \| MODERATE \| AGGRESSIVE	Preset tier. Individual fields override the preset.
`maxPerTransactionUsdc`	number	Hard cap per single transaction.
`dailyLimitUsdc`	number	Rolling 24-hour spend cap.
`monthlyLimitUsdc`	number	Rolling 30-day spend cap.
`allowedCategories`	string[]	Array of permitted category strings.
`blockedMerchants`	string[]	Array of blocked recipient addresses.
`allowedRecipients`	string[]	Explicit recipient allowlist. Empty = all allowed.
`requireApproval`	boolean	If true, all transactions enter PENDING state pending manual approval.

bash

curl -X POST https://nexuspay.app/api/policies \
  -H "X-Api-Key: nxp_live_sk_•••" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-gamma",
    "tier": "MODERATE",
    "maxPerTransactionUsdc": 25.00,
    "dailyLimitUsdc": 150.00,
    "allowedCategories": ["compute", "storage"]
  }'

x402 Paywall

x402 implements the HTTP 402 Payment Required standard for machine-to-machine micropayments. Register any API endpoint with a USDC price — when an agent hits it without a valid payment proof, they receive a 402 response with payment instructions. NexusPay auto-handles payment and retry transparently.

ℹSub-cent pricing is fully supported (e.g. 0.0001 USDC = $0.0001). This makes per-request monetisation economically viable for the first time.

List endpoints

GEThttps://nexuspay.app/x402

bash

curl https://nexuspay.app/api/x402 \
  -H "X-Api-Key: nxp_live_sk_•••"

Register endpoint

POSThttps://nexuspay.app/x402

Parameter	Type	Description
`path`REQUIRED	string	URL path to protect (e.g. /api/ml/inference).
`priceUsdc`REQUIRED	number	Price per request in USDC. Supports sub-cent values.
`description`	string	Human-readable endpoint description shown to paying agents.
`active`	boolean	Whether the paywall is enforced. Defaults to true.

bash

curl -X POST https://nexuspay.app/api/x402 \
  -H "X-Api-Key: nxp_live_sk_•••" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/api/premium/inference",
    "priceUsdc": 0.001,
    "description": "GPT-4o inference endpoint"
  }'

json

{
  "success": true,
  "data": {
    "id": "ep_Mnop789",
    "path": "/api/premium/inference",
    "priceUsdc": 0.001,
    "description": "GPT-4o inference endpoint",
    "active": true,
    "createdAt": "2026-04-01T12:10:00Z"
  }
}

Identity & Keys

NexusPay issues DID-compatible verifiable credentials so agents can prove their identity and spending authority to third-party services — without sharing private keys.

Issue credential

POSThttps://nexuspay.app/identity

Parameter	Type	Description
`agentId`REQUIRED	string	Agent to issue the credential for.
`claims`	object	Arbitrary claims to embed in the credential JWT.
`expiresInSeconds`	number	Credential TTL in seconds. Defaults to 3600 (1 hour).

Verify credential

POSThttps://nexuspay.app/identity/verify

Parameter	Type	Description
`token`REQUIRED	string	JWT credential issued by /identity.

json

{
  "success": true,
  "data": {
    "valid": true,
    "agentId": "agent-alpha",
    "claims": { "role": "buyer" },
    "expiresAt": "2026-04-01T13:00:00Z"
  }
}

Create API key

POSThttps://nexuspay.app/keys

⚠The plaintext key is returned only once. Copy it immediately — NexusPay stores only the SHA-256 hash.

Parameter	Type	Description
`agentId`REQUIRED	string	Agent wallet to bind this key to.
`label`	string	Human-readable label (e.g. 'production key').

json

{
  "success": true,
  "data": {
    "id": "key_QrSt456",
    "agentId": "agent-alpha",
    "key": "nxp_live_sk_AbCdEfGhIjKlMnOpQr",
    "label": "production key",
    "createdAt": "2026-04-01T12:15:00Z"
  }
}

Error Reference

All errors return a consistent shape with an HTTP status code and a human-readable message.

Status	Meaning	Common cause
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Missing or invalid X-Api-Key header
403	Policy Rejected	Spending policy blocked the transaction
404	Not Found	Agent ID or resource does not exist
409	Conflict	Insufficient balance (concurrent transaction race)
500	Internal Error	Unexpected server-side error

Ready to integrate?

Create your first agent wallet and start sending USDC payments in minutes.

Open Dashboard →