Blockchain network. Defaults to the environment's Base network when omitted ('base' on production, 'base-sepolia' on local/staging). Mainnet names sent to local/staging are coerced to their testnet counterpart (e.g. base → base-sepolia); testnet names sent to production are rejected with TESTNET_NOT_ALLOWED_IN_PRODUCTION.
orchestrationTypeenum"raw" · "coinbax"
Orchestration type: raw (direct blockchain) or coinbax (smart contract escrow)
templateIdstring (uuid)
Template ID from coinbax-library. The template will be fetched from the library service.
contractTemplateIdstring (uuid)
Contract template ID (alias for templateId, for backward compatibility)
templateobject
Complete template data embedded in request (optional, prefer using templateId instead)
TemplateDto
templateIdstringrequired
Template ID from coinbax-library
templateNamestringrequired
Template name
templateVersionstringrequired
Template version
controlsarray of TemplateControlDtorequired
Array of controls to execute
array of TemplateControlDto
idstringrequired
Control ID
typestringrequired
Control type (e.g., TimeDelay, TwoFactorAuth, ComplianceCheck)
Fee percentage in basis points (100 = 1%). Required for percentage type.
fixedFeeAmountnumber
Fixed fee amount in smallest currency unit. Required for fixed type.
tieredFeesarray of TieredFeeDto
Array of tiered fee configurations. Required for tiered type.
array of TieredFeeDto
minAmountnumberrequired
Minimum transaction amount for this tier
maxAmountnumberrequired
Maximum transaction amount for this tier
feePercentagenumberrequired
Fee percentage in basis points (100 = 1%)
feeWalletAddressstringrequired
Coinbax fee collection wallet address
currencystringrequired
Currency for fee collection
isActivebooleanrequired
Whether billing is active for this workspace
quoteIdstring (uuid)
FeeQuote id from a prior /transactions/quote call. Required when the workspace has BILLING_ENABLED=true (Phase 1 cutover).
signerTypeenum"custodial" · "external_wallet"
Signer type: custodial (Coinbax signs) or external_wallet (User signs via MetaMask)
customerIdstring
Customer ID for external wallet transactions (Transmitter users)
idempotencyKeystring
Idempotency key to prevent duplicate transaction creation. If provided, a transaction with the same key will return the existing transaction instead of creating a new one.
Responses
201Transaction created successfully
rescindobject
Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.
TransactionRescindInfo
allowedbooleanrequired
Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.
deadlineobjectrequired
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
object
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
requiresReasonbooleanrequired
Whether the rescind endpoint requires a non-empty `reason` field in the request body.
notifyRecipientbooleanrequired
Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.
Returns a paginated list of multi-recipient batches scoped to the calling platform. Legs are not embedded — fetch a single batch via GET /transactions/batch/:id for that.
Creates a parent batch row plus one Transaction leg per recipient in a single DB transaction. The client (e.g., SafeSend) then signs and submits `WorkspaceEscrow.batchCreateEscrow` with each leg's UUID as the on-chain `transactionId`. Per-leg `EscrowCreated` events flow through the existing event monitor and transition each leg from PENDING_USER_ACTION to ESCROWED individually.
Request body
fromAddressstringrequired
Sender blockchain address (one signer for the whole batch).
legsarray of CreateBatchLegDtorequired
Per-recipient legs (1..MAX_BATCH_LEGS).
array of CreateBatchLegDto
toAddressstringrequired
Receiver blockchain address for this leg.
amountnumberrequired
Per-leg amount (minimum 0.01, maximum 1,000,000).
metadataobject
Per-leg metadata (e.g., recipient name from the address book). Distinct from batch-level metadata.
object
Per-leg metadata (e.g., recipient name from the address book). Distinct from batch-level metadata.
Blockchain network. The set of accepted values mirrors `CreateTransactionDto.blockchainNetwork`, including the env-aware default ('base' on production, 'base-sepolia' on local/staging), non-prod coercion of mainnet names, and production rejection of testnet names.
orchestrationTypeenum"raw" · "coinbax"
Orchestration type for every leg.
signerTypeenum"custodial" · "external_wallet"
Signer type. Must be `external_wallet` in B1 — custodial batch sends are not supported in this phase.
templateIdstring (uuid)
Template ID from coinbax-library. Stored on the batch in B1; control execution against the template is wired in B2.
customerIdstring
Customer ID for external-wallet flows (Transmitter, SafeSend).
idempotencyKeystring
Idempotency key — if provided, an existing batch with the same key is returned instead of creating a new one.
metadataobject
Batch-level metadata (distinct from per-leg metadata).
object
Batch-level metadata (distinct from per-leg metadata).
templateobject
Embedded template (alternative to `templateId`, deprecated for consistency with `CreateTransactionDto`).
TemplateDto
templateIdstringrequired
Template ID from coinbax-library
templateNamestringrequired
Template name
templateVersionstringrequired
Template version
controlsarray of TemplateControlDtorequired
Array of controls to execute
array of TemplateControlDto
idstringrequired
Control ID
typestringrequired
Control type (e.g., TimeDelay, TwoFactorAuth, ComplianceCheck)
Returns the parent batch row plus all child Transaction legs. Each leg carries its own status, escrowId, and per-recipient metadata; per-leg listing of just the legs is also reachable via GET /transactions?batchId=…
Path parameters
idstringrequired
Responses
200Batch details with legs
object
{}
404Batch not found
Response follows the unified success / data / meta / error envelope.
Marks a batch FAILED and propagates the same status to every leg. Allowed only while the batch is in `pending_user_action` (the user hasn't signed `batchCreateEscrow` yet, or is parked awaiting verification). Once the on-chain tx is in flight, use per-leg refund/dispute endpoints instead. Idempotent on already-FAILED batches. Fires a `transaction.batch.failed` webhook on success.
Path parameters
idstringrequired
Request body
reasonstring
Human-readable reason recorded on the batch metadata. Surfaces in audit logs and the cancel webhook payload. Truncated at 500 chars.
Responses
200Batch cancelled (or was already FAILED — idempotent)
object
{}
400Batch is in a state that cannot be cancelled (submitted / completed)
Response follows the unified success / data / meta / error envelope.
404Batch not found
Response follows the unified success / data / meta / error envelope.
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/batch/<id>/cancel \
-H "X-API-Key: $COINBAX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Sender closed the tab before signing batchCreateEscrow"
}'
Stores the shared on-chain transaction hash on the batch + every leg, and advances the batch to `submitted`. Per-leg `EscrowCreated` events drive each leg from `pending_user_action` to `escrowed` independently via the existing event monitor.
Path parameters
idstringrequired
Request body
transactionHashstringrequired
On-chain transaction hash for the `batchCreateEscrow` call. Shared by every leg in the batch (one signature, one tx).
Responses
200Hash recorded, batch advanced to submitted
object
{}
400Batch is in a non-submittable state (already terminal, or still awaiting verification), or the request is for a custodial batch
Response follows the unified success / data / meta / error envelope.
404Batch not found
Response follows the unified success / data / meta / error envelope.
Accepts the verification code the sender received and clears the batch's `awaitingControlVerification` flag once every PRE_ESCROW verification control resolves.
Path parameters
idstringrequired
Request body
codestringrequired
6-digit verification code sent via SMS
Responses
200Code accepted, batch updated
object
{}
400Batch not awaiting verification, no pending 2FA control, or invalid/expired code
Response follows the unified success / data / meta / error envelope.
404Batch not found
Response follows the unified success / data / meta / error envelope.
Returns a 120-second-TTL quote with platform fee, workspace fee, gas pass-through (if applicable), and total charged. Pass the returned `quoteId` to `POST /transactions` to lock the rate.
Returns public-safe summaries of each active control on a template. Used by pre-confirmation surfaces (e.g. SafeSend) to render "What protects your send" panels and to enforce client-side AmountLimit min/max. Sanitized: only a hand-picked subset of each control config is returned — policy/implementation fields are NOT exposed.
Query parameters
templateIdstringrequired
Responses
200Template config retrieved
templateIdstringrequired
Template UUID.
templateNamestringrequired
Template name (e.g. "Transmitter P2P").
templateVersionstringrequired
Template version string from the library (e.g. "1.0.0").
controlsarray of TemplateControlSummaryrequired
Active controls on the template, sanitized to a small set of public-safe fields per type. See TemplateControlSummary.
array of TemplateControlSummary
typestringrequired
Control type. Tolerates the upstream `ChainlysisSanctions` typo alongside the corrected `ChainalysisSanctions` for now (see PR #74).
phasestringrequired
Execution phase: PRE_ESCROW, POST_ESCROW, PRE_RELEASE, or POST_RELEASE.
namestringrequired
Human-readable control name (from the template, e.g. "Sanctions Screening").
isRequiredbooleanrequired
Whether this control is required (vs. optional — driven by `metadata.optional` on the template control).
minAmountnumber
AmountLimit: minimum allowed amount per send (inclusive).
maxAmountnumber
AmountLimit: maximum allowed amount per send (inclusive).
currencystring
AmountLimit: currency the limits are denominated in (e.g. "USD", "USDC").
TimeDelay: whether the sender can rescind/cancel during the hold window.
userConfigurableboolean
TimeDelay: whether the user can pick a delay value per transaction (vs. always the template default). When true, the frontend should render `options` as selectable presets. When false or absent, the frontend renders the template default as a read-only display.
optionsarray of string
TimeDelay: allowed preset values (when `userConfigurable` is true) using compact duration notation: `Nm` minutes, `Nh` hours, `Nd` days. Frontend parses and renders these as picker chips. Empty / absent means no template-defined presets — frontend may fall back to its own defaults.
array of string
string
sanctionsListsarray of string
ChainlysisSanctions / ChainalysisSanctions: which sanctions lists the screening checks (e.g. OFAC, SDN, EU).
array of string
string
checksSenderboolean
ChainlysisSanctions / ChainalysisSanctions: whether the sender wallet is screened.
checksRecipientboolean
ChainlysisSanctions / ChainalysisSanctions: whether the recipient wallet is screened.
verificationRequiredboolean
TwilioSMS: whether the SMS-verification step is mandatory (vs. lookup-only).
Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.
TransactionRescindInfo
allowedbooleanrequired
Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.
deadlineobjectrequired
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
object
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
requiresReasonbooleanrequired
Whether the rescind endpoint requires a non-empty `reason` field in the request body.
notifyRecipientbooleanrequired
Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.
Runs the PRE_RELEASE controls and records the aggregate result on-chain for an external-wallet (SafeSend) COINBAX escrow, so the sender wallet (releaseEarly / releaseAfterDelay) can release without the escrow's PRE_RELEASE gate reverting. Call this immediately BEFORE the on-chain release write. An early (pre-window) release waives the time-delay hold; a required non-time control failure auto-rejects the escrow and refunds the sender (do not then attempt an on-chain release).
Path parameters
idstringrequired
Request body
earlyboolean
Advisory hint that the sender intends an early (pre-window) release. The server authoritatively infers early vs after-delay from the escrow release time and ignores this value for the decision.
Responses
200Release authorized (PRE_RELEASE attested Passed), or the escrow was rejected + refunded because a required control failed (see `rejected`).
Response follows the unified success / data / meta / error envelope.
400Not an external-wallet COINBAX escrow, not in ESCROWED status, or missing on-chain escrow id
Response follows the unified success / data / meta / error envelope.
404Transaction not found
Response follows the unified success / data / meta / error envelope.
Marks a transaction in PENDING_USER_ACTION as FAILED with userCancelled=true. No on-chain action — funds were never escrowed. Use this when the user rejects the wallet popup and does not intend to retry; rejects with 400 if the transaction has already advanced to ESCROWED (use /refund or /rescind instead) or is already terminal.
Path parameters
idstringrequired
Request body
reasonstring
Optional human-readable reason for the cancellation. Surfaced in the transaction.failed webhook and stored on `metadata.cancelReason`.
Responses
200Transaction cancelled successfully
rescindobject
Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.
TransactionRescindInfo
allowedbooleanrequired
Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.
deadlineobjectrequired
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
object
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
requiresReasonbooleanrequired
Whether the rescind endpoint requires a non-empty `reason` field in the request body.
notifyRecipientbooleanrequired
Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.
Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.
TransactionRescindInfo
allowedbooleanrequired
Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.
deadlineobjectrequired
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
object
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
requiresReasonbooleanrequired
Whether the rescind endpoint requires a non-empty `reason` field in the request body.
notifyRecipientbooleanrequired
Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.
Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.
TransactionRescindInfo
allowedbooleanrequired
Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.
deadlineobjectrequired
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
object
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
requiresReasonbooleanrequired
Whether the rescind endpoint requires a non-empty `reason` field in the request body.
notifyRecipientbooleanrequired
Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.
Allows the sender to cancel a transaction during the Payment Hold Period and have funds returned to their wallet. Only available if the TimeDelay control has allowSenderRescind enabled.
Path parameters
idstringrequired
Request body
reasonstring
Reason for rescinding the transaction (required if control config has rescindRequiresReason: true)
senderWalletstringrequired
Sender wallet address for authorization verification
Responses
200Transaction rescinded successfully, funds returned to sender
rescindobject
Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.
TransactionRescindInfo
allowedbooleanrequired
Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.
deadlineobjectrequired
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
object
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
requiresReasonbooleanrequired
Whether the rescind endpoint requires a non-empty `reason` field in the request body.
notifyRecipientbooleanrequired
Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.
400Transaction cannot be rescinded (not in ESCROWED status, rescind not enabled, or rescind window expired)
Response follows the unified success / data / meta / error envelope.
403Only the sender can rescind a transaction
Response follows the unified success / data / meta / error envelope.
404Transaction not found
Response follows the unified success / data / meta / error envelope.
curl -X POST https://api-staging.coinbax.com/api/v1/transactions/<id>/rescind \
-H "X-API-Key: $COINBAX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Changed my mind about the purchase",
"senderWallet": "0x1234567890abcdef1234567890abcdef12345678"
}'
const response = await fetch('https://api-staging.coinbax.com/api/v1/transactions/<id>/rescind', {
method: 'POST',
headers: {
'X-API-Key': process.env.COINBAX_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"reason": "Changed my mind about the purchase",
"senderWallet": "0x1234567890abcdef1234567890abcdef12345678"
}),
});
const result = await response.json();
Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.
TransactionRescindInfo
allowedbooleanrequired
Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.
deadlineobjectrequired
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
object
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
requiresReasonbooleanrequired
Whether the rescind endpoint requires a non-empty `reason` field in the request body.
notifyRecipientbooleanrequired
Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.
After the user deposits USDC to the escrow contract via MetaMask, submit the transaction hash and escrow ID to confirm the escrow was created
Path parameters
idstringrequired
Request body
transactionHashstringrequired
Blockchain transaction hash from user wallet escrow deposit
escrowIdstring
Escrow ID returned by the smart contract (optional - will be detected from blockchain events if not provided)
Responses
200Escrow hash submitted and verified successfully
rescindobject
Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.
TransactionRescindInfo
allowedbooleanrequired
Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.
deadlineobjectrequired
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
object
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
requiresReasonbooleanrequired
Whether the rescind endpoint requires a non-empty `reason` field in the request body.
notifyRecipientbooleanrequired
Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.
After sending USDC from your wallet, submit the transaction hash to complete the transaction
Path parameters
idstringrequired
Request body
transactionHashstringrequired
Blockchain transaction hash from user wallet
Responses
200Transaction hash submitted and verified successfully
rescindobject
Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.
TransactionRescindInfo
allowedbooleanrequired
Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.
deadlineobjectrequired
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
object
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
requiresReasonbooleanrequired
Whether the rescind endpoint requires a non-empty `reason` field in the request body.
notifyRecipientbooleanrequired
Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.
2002FA verified successfully, transaction can proceed
rescindobject
Public-safe summary of the TimeDelay rescind config. Lets clients gate the Cancel/Rescind affordance without a second round-trip. Null when the transaction has no TimeDelay control (RAW orchestration, templates without a hold period). Absent from response on the list endpoint and on legacy api revisions.
TransactionRescindInfo
allowedbooleanrequired
Whether the sender is allowed to rescind/cancel the transaction during the hold window. Defaults to true when not explicitly set on the underlying control config.
deadlineobjectrequired
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
object
ISO 8601 timestamp after which rescind is no longer allowed. Null when the rescind window matches the full hold period.
requiresReasonbooleanrequired
Whether the rescind endpoint requires a non-empty `reason` field in the request body.
notifyRecipientbooleanrequired
Whether the recipient is notified (e.g. via SMS) when a rescind succeeds.