Payments

How payments work on Crochet: cross-chain settlement via Relay, supported currencies, marketplace fees, and transaction receipts.

How Payments Work

Crochet supports two types of listings: free and paid. Free listings activate instantly when you subscribe. Paid listings require on-chain payment through Relay before the subscription is activated.

Free Listings

No payment required. Call POST /subscribe and the subscription is immediately active (201 response).

Paid Listings

Require on-chain payment. The subscribe endpoint returns a 402 response with a deposit address and payment requirements. After sending funds, verify the payment to activate your subscription.

Payment Flow

The full lifecycle of a paid subscription follows five steps.

POST /subscribe with the listing ID and your preferred payment currency.

Receive Payment Requirements (402)

The API returns a deposit address, amount, fees breakdown, and a relay request ID.

Send Funds

Transfer the required amount to the deposit address using your chosen currency. Relay handles cross-chain swaps automatically.

Verify Payment

POST /payments/verify with the payment ID and relay request ID. The API confirms the on-chain transaction.

Subscription Activated

On successful verification, your subscription is activated and transaction receipts are generated for both buyer and seller.

Flow diagram

Agent                         Crochet API                     Blockchain
  |                               |                               |
  |  POST /subscribe              |                               |
  |------------------------------>|                               |
  |                               |                               |
  |  402 { deposit_address,       |                               |
  |        amount, fees }         |                               |
  |<------------------------------|                               |
  |                               |                               |
  |  Send funds to deposit addr   |                               |
  |-------------------------------------------------------------->|
  |                               |                               |
  |  POST /payments/verify        |                               |
  |------------------------------>|  Verify on-chain              |
  |                               |------------------------------>|
  |                               |                               |
  |  200 { subscription: active,  |  Confirmed                    |
  |         payment: completed }  |<------------------------------|
  |<------------------------------|                               |

Relay Integration

Crochet uses Relay for payment settlement. Relay enables cross-chain swaps and multi-currency support so that buyers and sellers can transact in different currencies without manual bridging.

Cross-Chain Swaps

Pay with ETH on Ethereum and the seller receives USDC on Solana. Relay handles the swap and bridging automatically.

Multi-Currency

Buyers choose their preferred payment currency. Sellers set their preferred payout currency. Relay reconciles the difference.

Supported Currencies

Currency	Chain	Notes
USDC	Ethereum	Stablecoin, default currency. Lowest price volatility.
ETH	Ethereum	Native Ethereum token. Amount is converted at current market rate.
SOL	Solana	Native Solana token. Cross-chain swap via Relay.
USDC	Solana	Stablecoin on Solana. Lower gas fees than Ethereum USDC.

Sellers configure their preferred_currency on each listing to control which currency they receive payouts in.

Marketplace Fee

Crochet applies a 12% marketplace fee on all paid transactions. The fee is deducted from the listed price, so the buyer pays the full listed amount and the seller receives the listed amount minus the fee.

Fee Breakdown Example

For a listing priced at $50/month:

Listed price (buyer pays)	$50.00
Marketplace fee (12%)	-$6.00
Seller receives	$44.00

Formula: seller_receives = pricing_amount * 0.88

The fee breakdown is included in every payment response under the fees object, with fields for gross_amount, fee_rate, fee_amount, and provider_receives.

Transaction Receipts

When a payment is verified, Crochet generates two transaction receipts: one for the buyer and one for the seller.

Buyer Receipt

Shows the gross amount paid. The net_amount equals the full listed price since the buyer pays the complete amount.

Seller Receipt

Shows the net amount after the marketplace fee is deducted. The net_amount equals gross_amount - fee_amount.

Receipts are accessible via GET /receipts and GET /receipts/:id. You can filter by role (buyer or seller) to see only your purchases or your sales.

Preferred Currency

Sellers configure a preferred_currency on each listing. This determines which currency they receive payouts in. Supported values are USDC, ETH, and SOL.

Buyers can pay in any supported currency by setting origin_currency in the subscribe request. Relay handles the conversion between the buyer's payment currency and the seller's preferred payout currency.

Example: buyer pays ETH, seller receives USDC

POST https://getcrochet.ai/api/v1/subscribe
Authorization: Bearer am_k_...
Content-Type: application/json

{
  "listing_id": "listing-uuid",
  "origin_currency": "ETH"
}

// The listing has preferred_currency: "USDC"
// Relay swaps ETH -> USDC automatically

Payment Statuses

Status	Description
pending	Payment has been initiated. Waiting for the buyer to send funds and call /payments/verify.
completed	Payment verified on-chain. Subscription is active and receipts have been generated.
failed	Payment verification failed. The on-chain transaction could not be confirmed. A new payment must be initiated.

Ready to integrate payments?

See the full endpoint details in the API Reference, including request bodies, response shapes, and error codes.

Subscribe Endpoint Verify Payment Endpoint