Changelog

New updates and improvements

Track API changes, new features, migration guides, and deprecation notices.

Each release starts with the headline changes first. Expand the examples when you need implementation detail.

March 1, 2026

v2.1.0 — x402 Agent Payments, Base, and Arbitrum

New endpoints now support AI agent payments with gasless stablecoin transfers. Base and Arbitrum are also now supported across payment sessions and agent payments.

Highlights

• Added POST /payments/agent/settle
• Added POST /payments/agent/verify
• Added x402 payment session support
• Added Base and Arbitrum support

Agent payments

POST /payments/agent/settle

Settle gasless stablecoin payments from AI agents. This endpoint accepts signed payloads from:

• eip3009 for USDC on Base and Arbitrum
• permit2 for USDC and USDT on Base, Arbitrum, and BSC
• solana for SOL, USDC, and USDT on Solana

CoinCircuit submits the transaction on-chain and covers gas.

Example request

POST /api/v1/payments/agent/settle
{
  "sessionReference": "cs_ref_abc123",
  "scheme": "eip3009",
  "chain": "base",
  "asset": "USDC",
  "payload": {
    "from": "0xAgentWallet...",
    "to": "0xDepositAddress...",
    "value": "1000000",
    "validAfter": "0",
    "validBefore": "1774055094",
    "nonce": "0xrandom32bytes...",
    "signature": "0xabcd...1234"
  }
}

POST /payments/agent/verify

Pre-validate a signed agent payment before touching the blockchain. This runs scheme-specific checks and returns 200 for a valid payment, or 400 with per-check results.

Example request and response

POST /api/v1/payments/agent/verify
{
  "scheme": "eip3009",
  "chain": "base",
  "asset": "USDC",
  "payload": { ... }
}

{
  "valid": true,
  "checks": {
    "balance": "pass",
    "nonce": "pass",
    "authorization": "pass"
  }
}

x402 HTTP 402 payment flow

Payment sessions now work in the x402 flow.

1

Create a payment session

Create a session with POST /payments.

2

Return 402 Payment Required

Return deposit details to the agent in the 402 response.

3

Receive the signed payload

The agent signs the payment with eip3009, permit2, or solana.

4

Settle the payment

Call POST /payments/agent/settle and deliver the resource.

View end-to-end flow

Agent -> GET /api/premium-data
Server -> CoinCircuit: POST /payments
Server -> Agent: 402 (deposit address, amount)
Agent -> Signs payment (eip3009 / permit2 / solana)
Agent -> Server: POST /pay (signed payload)
Server -> CoinCircuit: POST /payments/agent/settle
Server -> Agent: 200 (resource delivered)

Supported schemes and chains

• eip3009 — USDC on Base and Arbitrum
• permit2 — USDC and USDT on Base, Arbitrum, and BSC
• solana — SOL, USDC, and USDT on Solana

New supported blockchains

Base

Base is now supported for all payment sessions. USDC on Base settles in under 2 seconds. Base is also the default chain for EIP-3009 agent payments.

Arbitrum

Arbitrum One is now supported for all payment sessions. It supports USDC and USDT with both EIP-3009 and Permit2.

February 1, 2026

v2.0.0 — Payment API Transition and Payouts Unified

This release updates payment session payloads, renames webhook event types, and introduces a unified payouts API. Existing API keys keep their current behavior. New API keys use the updated format automatically.

Highlights

• Renamed webhook event types from session.* to payment.*
• Redesigned payment session response shape
• Added inline settlements
• Unified payouts under POST /payouts
• Deprecated legacy payout endpoints

Payment API changes

Webhook event types renamed

Payment session event names now use payment.* instead of session.*. The payload shape stays the same. Only the event type string changes.

Previous

"session.completed"
"session.expired"
"session.partial"
"session.failed"

New

"payment.completed"
"payment.expired"
"payment.partial"
"payment.underpaid"
"payment.failed"

New API keys use the updated format automatically

Versioning is tied to your API key:

• Existing API keys keep the current response shape and event types
• New API keys use the updated response shape and webhook names
• No extra config is required

No change is required to keep your current integration working. Create a new API key only when you are ready to adopt the new format.

Session response shape redesigned

The session response is now flatter:

• status is replaced by state
• amount and currency are now top-level strings
• gross, fees, and net move to settlements

View full session response example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "cs_ref_abc123xyz789",
  "state": "closed",
  "type": "payment",
  "amount": "10000.00",
  "currency": "NGN",
  "payment": {
    "status": "completed",
    "asset": "USDT",
    "chain": "tron",
    "amount": "6.84",
    "amountReceived": "6.84",
    "address": "T...",
    "txHash": "0x..."
  },
  "settlements": {
    "currency": "NGN",
    "gross": { "amount": "10000.00", "conversionRate": "1.0" },
    "fees": {
      "processing": { "amount": "100.00", "paidBy": "merchant" },
      "gas": { "amount": "50.00", "paidBy": "merchant" }
    },
    "net": { "amount": "9850.00" }
  },
  "customer": { ... },
  "createdAt": "...",
  "expiresAt": "...",
  "completedAt": "..."
}

state replaces status

The top-level session status is now binary:

• open while the session is active
• closed once the session is finalized

The payment outcome now lives in payment.status.

Previous

{ "status": "completed" }  // "pending" | "completed" | "expired" | "failed"

New

{ "state": "closed" }      // "open" | "closed"
// payment outcome lives in payment.status

settlements is now included in the payment response

Payment session responses now include settlement details inline. You no longer need a separate settlements lookup for the same breakdown.

View `settlements` example

{
  "settlements": {
    "currency": "NGN",
    "gross": { "amount": "10000.00", "conversionRate": "1.0" },
    "fees": {
      "processing": { "amount": "100.00", "paidBy": "merchant" },
      "gas": { "amount": "50.00", "paidBy": "merchant" }
    },
    "net": { "amount": "9850.00" }
  }
}

Payouts API changes

/payout/fiat and /payout/crypto are deprecated. They will be removed on March 30, 2026.

Legacy payout endpoints replaced by /payouts

Use the unified payouts API for both fiat and crypto payouts. Fee lookup is also now unified.

Previous

POST /payout/fiat
POST /payout/crypto
GET  /payout/fiat/fee
GET  /payout/crypto/fee

New

POST /payouts
GET  /payouts/fees

Unified payout request body

Use method to choose fiat or crypto. Use recipientId instead of bankAccountId or addressId.

View example request

{
  "method": "fiat",
  "currency": "NGN",
  "amount": "10000.00",
  "recipientId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "narration": "Payout",
  "reference": "CLIENT-REF-123"
}

Amount now means what the recipient receives

The old API treated amount as the total deducted from your balance. The new API treats amount as the amount delivered to the recipient. Fees are charged separately.

Previous

{ "amount": "10050.00" }
// fee: 50.00
// recipient gets: 10000.00

New

{ "amount": "10000.00" }
// fee: 50.00
// total deducted: 10050.00

Payout response redesigned

The response now uses flat amount fields, a unified recipient object, and a conversion object when payout currency differs from the balance currency.

View full payout response example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "method": "crypto",
  "type": "manual",
  "status": "success",
  "amount": "100.00",
  "fee": "1.50",
  "total": "101.50",
  "currency": "USDC",
  "conversion": {
    "from": "USDT",
    "to": "USDC",
    "rate": "0.9998",
    "convertedAmount": "100.00"
  },
  "recipient": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "type": "cryptoAddress",
    "address": "T...",
    "chain": "tron",
    "asset": "USDC"
  },
  "txHash": "0x...",
  "reference": "CLIENT-REF-123",
  "narration": "Payout",
  "createdAt": "...",
  "completedAt": "..."
}

Migration guide

Follow these steps to move to the new format. You can adopt them incrementally.

1

1. Generate a new API key

New API keys automatically use the updated format. Keep your existing key for the current integration. Test the new key before switching production traffic.

2

2. Update webhook event handlers

Replace session.* event strings with payment.* equivalents in your webhook handler.

"session.completed" -> "payment.completed"
"session.expired"   -> "payment.expired"
"session.partial"   -> "payment.partial"
"session.failed"    -> "payment.failed"

3

3. Update payment.partial handling

payment.partial is now strictly mid-flow. It only fires when the session is still open and waiting for more funds. Terminal underpayment now emits payment.underpaid.

if (event === "payment.partial") {
  // data.session.state === "open"
  notifyCustomerOfPartialPayment(data.session.payment.amountReceived);
}

if (event === "payment.underpaid") {
  // data.session.state === "closed"
  initiateRefundFlow(data.session.payment.amountReceived);
}

4

4. Update session response parsing

Move parsing logic from nested amount fields to top-level amount, currency, and settlements.

// Previous
session.status
session.amount.requested.amount
session.amount.requested.currency
session.amount.gross
session.amount.fees
session.amount.net

// New
session.state
session.amount
session.currency
session.settlements.gross
session.settlements.fees
session.settlements.net

5

5. Migrate payout endpoints

Replace legacy payout endpoints with POST /payouts. Add method to the request body. Replace bankAccountId or addressId with recipientId. Replace fee lookups with GET /payouts/fees.

// Old
POST /payout/fiat   { balanceCurrency, amount, bankAccountId, narration }
POST /payout/crypto { balanceCurrency, amount, addressId }

// New
POST /payouts {
  method: "fiat" | "crypto",
  currency: "NGN",
  amount: "10000.00",
  recipientId: "...",
  narration: "...",
  reference: "..."
}

6

6. Update payout amount handling

Remove any logic that adds fees into the request amount. In the new API, amount is the amount the recipient receives.

// Old
const amount = recipientAmount + fee;
POST /payout/fiat { amount: "10050.00" }

// New
POST /payouts { amount: "10000.00" }

7

7. Update payout response parsing

Move response parsing from nested amount and endpoint-specific recipient objects to flat fields and the unified recipient object.

// Old response fields
payout.amount.gross
payout.amount.fee
payout.amount.net
payout.amount.currency
payout.bankAccount
payout.crypto.amount
payout.crypto.chain
payout.crypto.address

// New response fields
payout.amount
payout.fee
payout.total
payout.currency
payout.recipient.type
payout.recipient.address
payout.recipient.chain
payout.recipient.bankName
payout.conversion