API Reference

Authentication

Authenticate requests by including your API key in the Authorization header as a Bearer token. API keys come in two forms — test keys (proco_test_…) for sandbox and live keys (proco_live_…) for production.

Authorization header

http

Authorization: Bearer proco_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx

Sandbox: All API calls made with a proco_test_ key are simulated. No real USDC moves. The response shape is identical to production.

Create a payment

Creates and immediately executes a USDC payment. Proco auto-routes to the optimal chain unless chain is specified. Compliance is run automatically when compliance: 'auto'.

POST /payments

Parameter	Type	Description
torequired	string	Recipient USDC wallet address (EVM hex or Solana base58)
amountrequired	string	Amount in USDC, as a decimal string. e.g. `"500.00"`
currency	string	Defaults to `"USDC"`. Also accepts `"EURC"`.
chain	string	Chain to use: `"auto"` (default), `"base"`, `"solana"`, `"ethereum"`
compliance	string	`"auto"` runs full KYC/AML/sanctions stack. `"skip"` for pre-cleared parties (Enterprise only)
from	string	Optional wallet ID for multi-wallet setups. Defaults to your primary treasury.
memo	string	Freeform string attached to the on-chain transaction. Max 64 chars.
idempotency_key	string	Unique key to safely retry requests. Same key returns the original payment object.

typescript

const payment = await proco.payments.create({
  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  amount: '500.00',
  currency: 'USDC',
  chain: 'auto',
  compliance: 'auto',
  memo: 'Invoice #1042',
  idempotency_key: 'inv-1042-2026-03-24',
});

Response

json

{
  "id": "pay_01HXYZ4ABCDEF",
  "status": "settled",
  "txHash": "0x4a2f1c8d...",
  "to": "0x742d35Cc...",
  "amount": "500.00",
  "currency": "USDC",
  "chain": "base",
  "memo": "Invoice #1042",
  "compliance_ref": "cpl_01HX...",
  "created_at": "2026-03-24T14:32:00Z",
  "settled_at": "2026-03-24T14:32:08Z",
  "settlement_ms": 8240
}

Get a payment

Retrieves the current state of a payment by ID. For pending payments, poll until status is "settled" or "failed" — or use webhooks instead.

GET /payments/:id

typescript

const payment = await proco.payments.get('pay_01HXYZ4ABCDEF');

Create a wallet

Creates a new programmable, non-custodial USDC wallet. Use for agent wallets, user wallets, or escrow accounts. Spend limits and approval thresholds are encoded at creation and enforced at the protocol level.

POST /wallets

Parameter	Type	Description
ownerrequired	string	Owner identifier. Use `"agent:name"` for agent wallets or `"user:id"` for user wallets.
chainrequired	string	`"base"`, `"solana"`, or `"ethereum"`
spend_limit	string	Max USDC per 24-hour window without explicit approval. e.g. `"100.00"`
compliance	string	`"auto"` (default) — runs identity verification at wallet creation
label	string	Human-readable label for the wallet. Not on-chain.

typescript

const wallet = await proco.wallets.create({
  owner: 'agent:orchestrator-01',
  chain: 'solana',
  spend_limit: '10.00',
  compliance: 'auto',
  label: 'Orchestrator primary',
});

// wallet.address is ready to receive and send immediately
console.log(wallet.address); // HN7cABqLq46Es1jh92dQQisAi18...

Treasury

Your treasury is the primary USDC balance used for outbound payments. Check balance, set routing rules, and configure yield destinations.

GET /treasury/balance

typescript

const balance = await proco.treasury.getBalance();
// { usdc: "48,320.00", chains: { base: "30000", solana: "18320" } }

Compliance

Run a standalone compliance check before initiating a payment. Returns a compliance_ref that can be passed to /payments to skip re-screening. Results are cached for 24 hours.

POST /compliance/check

Parameter	Type	Description
addressrequired	string	Wallet address to screen
checks	string[]	Array of checks to run: `"kyc"`, `"aml"`, `"sanctions"`, `"travel_rule"`. Defaults to all.
country_code	string	ISO 3166-1 alpha-2 country code. Required for sanctions screening.

typescript

const result = await proco.compliance.check({
  address: '0x742d35Cc...',
  checks: ['kyc', 'sanctions'],
  country_code: 'DE',
});
// { status: 'cleared', ref: 'cpl_01HX...', expires_at: '...' }

Webhook events

Proco sends signed webhook events to your endpoint. All events include a type, data object, and a proco-signature header for verification.

Event	Description
payment.settled	Payment confirmed on-chain. Includes `txHash`, `settlement_ms`, and `compliance_ref`.
payment.failed	Payment could not be settled. Includes `error_code` and `error_message`.
payment.compliance_blocked	Compliance check failed — OFAC match or AML flag. Payment not executed.
wallet.funded	A wallet received inbound USDC. Includes `amount`, `from`, and `txHash`.
wallet.spend_limit_reached	An agent wallet has reached its 24-hour spend limit. Approval required to continue.
treasury.low_balance	Treasury USDC balance has dropped below your configured threshold.

typescript

import { Proco } from '@proco/sdk';

app.post('/webhooks/proco', (req, res) => {
  const event = proco.webhooks.verify({
    payload: req.body,
    signature: req.headers['proco-signature'],
    secret: process.env.PROCO_WEBHOOK_SECRET,
  });

  switch (event.type) {
    case 'payment.settled':
      // update your records
      break;
    case 'payment.compliance_blocked':
      // alert your compliance team
      break;
  }

  res.json({ received: true });
});

Errors

Proco uses standard HTTP status codes. All errors return a JSON body with code and message fields.

HTTP	Code	Description
400	`invalid_request`	Missing or malformed parameters. Check the `message` field for details.
401	`unauthorized`	Invalid or missing API key.
402	`insufficient_balance`	Treasury USDC balance is too low to execute the payment.
403	`compliance_blocked`	Recipient failed compliance screening. Payment not executed.
404	`not_found`	The requested resource does not exist.
409	`idempotency_conflict`	The idempotency key was used with different parameters.
422	`chain_unavailable`	The selected chain is temporarily unavailable. Retry with `chain: 'auto'`.
429	`rate_limited`	Too many requests. See rate limits.
500	`internal_error`	Something went wrong on our end. Retry after a short delay.

Rate limits

Limits are per API key. Enterprise plans have significantly higher limits — contact us if you need more.

100/s

Payments (Scale)

Per-second limit on POST /payments. Burst up to 200/s for 5 seconds.

1,000/s

Payments (Enterprise)

Custom burst limits available. Contact us for throughput above 1,000/s.

50/s

Compliance checks

Standalone POST /compliance/check calls. Cached results don't count against the limit.

20/s

Wallet creation

Agent wallet provisioning. Use bulk wallet creation for initial setup.

SDKs

Official SDKs abstract chain routing, gas, retry logic, and webhook verification. Start with TypeScript — it has the most complete coverage.

TypeScript / Node.js

npm install @proco/sdk

● Live · v2.1.0

Python

pip install proco-sdk

● Live · v1.4.0

Go

go get github.com/procohq/go

○ Beta · Q2 2026

REST API: All SDKs are thin wrappers over the REST API. You can call https://api.procohq.com/v1 directly with any HTTP client — just include your API key in the Authorization header.