codespar_crypto_pay

Use it when the buyer or recipient settles in stablecoin or another crypto asset instead of fiat. For Pix, card, boleto or wire, that is codespar_pay.

Actions

Example

direction: "receive" on Coinbase Commerce: a hosted checkout the buyer settles in USDC. country: "INTL" is what selects that line (see Arguments); without it the intent defaults to BR and lands on the Bitso withdrawal line.

{
  "name": "codespar_crypto_pay",
  "arguments": {
    "amount": 10,
    "currency": "USDC",
    "direction": "receive",
    "country": "INTL",
    "metadata": { "order_id": "order_0000" }
  }
}

When to use

• Stablecoin checkout (the buyer pays in USDC on a hosted page): direction: "receive", country: "INTL". The buyer is anonymous until they hit the hosted URL, so counterparty can be omitted.
• An on-chain USDC payout to an external address: direction: "send", country: "BR" (the Bitso withdrawal line), with counterparty.address and counterparty.country.
• Fiat ↔ USDC ramps through the on/offramp partner: rail: "onramp" (a buyer sends Pix BRL, US wire or EUR SEPA and the operator's USDC wallet receives the stablecoin leg) or rail: "offramp" (the operator sends USDC and the recipient receives fiat on a pre-registered bank account), both with country: "INTL". A cross-border purchase chains the two.
• Match the direction to the rail yourself. The router's money-direction guard runs only for codespar_pay, so a receive that resolves to the send-only Bitso line is dispatched, not refused.

Arguments

The published schema declares six fields. Two more (rail, country) are read by the router and not declared; an agent working from the schema alone never passes them and every call resolves to the Bitso line.

Errors and what to do

Money and mandate

direction: "send" moves real money through the connected provider (a Bitso withdrawal, a Foxbit order, an offramp transfer) and follows your key's environment: a csk_test_ key hits the provider's sandbox, a live key moves real money. direction: "receive" creates a hosted checkout or deposit instructions and nothing moves until the buyer pays. These are provider rails, not on-chain settlement by CodeSpar: the x402 / CDP wallet path is a different surface with its own network gate, described in the gate. The wallet's USDC slot and its per-currency cap are described on codespar_wallet.

Related

• codespar_pay: the fiat rails
• codespar_charge: the fiat inbound counterpart
• codespar_wallet: the multi-slot wallet, including the USDC slot
• hmac_signed auth: the Bitso and Foxbit authentication pattern
• Crypto Pay Agent cookbook: end-to-end stablecoin example
• Async settlement

Notes

Rails. The six catalog lines for codespar_crypto_pay. The router matches (rail, currency, country) exactly; there is no wildcard fallback.

There is no stablecoin-payout rail: an on-chain USDC payout is rail: "stablecoin", country: "BR", direction: "send".

Cross-border purchase (BR buyer → US merchant). Two calls: an onramp receive (country: "INTL", counterparty: { country: "BR" }, metadata: { fiat_currency: "BRL" }) that returns the Pix copia-e-cola the buyer settles, then an offramp send (country: "INTL", counterparty: { country: "US", bank_account_id }, metadata: { fiat_currency: "USD" }) that pays the merchant by wire. No card flag, no IOF, no SWIFT.

Operator setup. Coinbase Commerce: api_key auth with the X-CC-Api-Key header, optional shared secret for webhook verification. Bitso and Foxbit: hmac_signed auth; the operator stamps API key and secret and the runtime signs each request with HMAC-SHA256 over nonce + method + path + body. On/offramp partner: api_key auth with a raw Authorization: <api_key> header (no Bearer prefix); the operator pre-funds a USDC wallet and the runtime injects its id as sourceWalletId.

Async settlement. Crypto rails settle on-chain; latency varies by chain (seconds on Base and Polygon, minutes on Bitcoin). The flow mirrors codespar_charge: the call returns an id and a pending status (and, for receives, the hosted URL), the buyer pays or the transfer executes, the provider webhook lands and is correlated by idempotency_key, and session.paymentStatus(id) returns succeeded, expired (abandoned) or failed (chain error).

Result shape (SDK), as previously documented. { id, status, amount, currency, network?, direction, hosted_url?, addresses?, pix_deposit_code?, crypto_deposit_address?, raw? } under data (reading charge.hosted_url instead of charge.data.hosted_url yields undefined). This revision did not re-verify that list against the runtime.

From the SDK. There is no typed wrapper; session.execute("codespar_crypto_pay", arguments) takes the same arguments as the MCP call.