Skip to navigation

Create an ad

Creates an ad. Approved advertisers only. Scope p2p.ads. A buy ad needs the account’s cashout unblocked (423 cashout_locked): the order amount is held from this account. Outside the account’s cashout hours the buy ad is created but stays off the market (hiddenReason) until the window opens.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
X-Acting-DocumentstringOptional

CPF of the human performing the operation. Required on cashout routes when the credential enforces a transaction PIN. On a company P2P profile contact, this CPF is the holder who signs; it is not taken from the body.

Idempotency-KeystringOptional

Optional client-generated idempotency token (recommended for safe retries).

Request

This endpoint expects an object.
sideenumOptional

sell: you sell crypto for BRL. Required on creation.

Allowed values:
pairstringOptional
Required on creation.
priceModeenumOptional

spread: basis points over the Binance spot. fixed: fixed BRL price. offset: a signed BRL amount (4 decimal places) added to the Binance spot. The unit price always has 4 decimal places; the order amount rounds down to cents at opening and the fee rounds up. The fee rate stays in basis points of the order amount, whatever the mode.

Allowed values:
spreadBpsintegerOptional-500-500

spread mode: spread over the Binance spot price at the moment. The listed price is indicative; the order locks the spread over the spot captured at opening.

fixedPricestringOptional

fixed mode: fixed BRL price per unit, up to 4 decimal places. The order locks this price as-is; only the BRL amount rounds to cents at opening.

offsetstringOptional

offset mode: signed BRL amount per unit added to the Binance spot, up to 4 decimal places (-0.0100 buys one cent below, 0.0001 is one ten-thousandth). Must stay within 5% of the current spot (422 invalid_offset); without a Binance quote when publishing or changing the offset, 409 price_unavailable.

stockAmountstringOptional

Crypto amount offered (sell) or wanted (buy).

limitsUnitenumOptional

Unit of the per-order range. brl (default): minAmount/maxAmount in BRL. asset: minAssetAmount/maxAssetAmount in crypto, and the opening compares the order crypto amount against them. Sending the fields of the other unit is 400 invalid_payload; switching units requires both bounds in the new unit (400 missing_fields). With asset, a Binance quote is needed when the range or the price changes (409 price_unavailable), because the BRL equivalent is what the per-order cap and the buy-ad autopause measure.

Allowed values:
minAmountstringOptional

Minimum BRL per order (limitsUnit brl).

maxAmountstringOptional

Maximum BRL per order (capped by tenant and advertiser caps; limitsUnit brl).

minAssetAmountstringOptional

Minimum crypto per order, up to the pair decimals (limitsUnit asset).

maxAssetAmountstringOptional

Maximum crypto per order (limitsUnit asset). Its BRL equivalent is still capped by tenant and advertiser caps.

deliveryDeadlineMinintegerOptional
Minutes the seller has to send after both sign.
instructionsstringOptional<=500 characters
walletIdstringOptional

Approved wallet: source (sell) or destination (buy).

statusenumOptional
PATCH only.
Allowed values:
offsetCentsintegerOptionalDeprecated

Deprecated. Whole BRL cents; 1 is stored as 0.0100. Prefer offset. Ignored when offset is also sent.

Response

Ad created
adIdstringOptional
Ad identifier.
sideenumOptional
Advertiser side.
Allowed values:
pairstringOptional
Pair code.
priceModeenumOptional

Pricing: spread (bps over the Binance spot), fixed (fixed BRL price) or offset (signed BRL amount, 4 decimal places, over the Binance spot).

Allowed values:
spreadBpsintegerOptional

spread mode: basis points over the Binance spot.

offsetstringOptional

offset mode: signed BRL amount per unit added to the Binance spot, 4 decimal places. Requests may still send the deprecated integer offsetCents; responses only send offset.

pricestring or nullOptional

Current BRL price per unit, 4 decimal places; null without a usable quote.

fixedPricestringOptional

Fixed price per unit, 4 decimal places (owner).

limitsUnitenumOptional

Unit the advertiser set the per-order range in.

Allowed values:
minAmountstringOptional

Minimum BRL per order. With limitsUnit asset it is minAssetAmount at the price shown, so it moves with the price.

maxAmountstringOptional

Maximum BRL per order. With limitsUnit asset it is maxAssetAmount at the price shown.

minAssetAmountstringOptional

Minimum crypto per order. Only with limitsUnit asset.

maxAssetAmountstringOptional

Maximum crypto per order. Only with limitsUnit asset.

availableAmountstringOptional

Crypto available (stock minus reserved).

stockAmountstringOptional

Total stock (owner).

reservedAmountstringOptional

Reserved by open orders (owner).

walletIdstringOptional

Ad wallet (owner).

deliveryDeadlineMinintegerOptional
Minutes to send after both sign.
instructionsstringOptional
Advertiser instructions.
instructionsFlaggedbooleanOptional

Instructions flagged for review (owner).

statusenumOptional
Ad status.
Allowed values:
pausedReasonstringOptional

Why the ad was paused automatically (owner). cashout_locked means the holder blocked the account’s cashout; reactivate after unblocking.

hiddenReasonenumOptional

Owner only, active buy ads: why the market is not showing the ad right now. cashout_locked: cashout blocked; cashout_outside_hours: outside the account’s cashout hours (comes back when the window opens).

Allowed values:
advertiserobjectOptional

Advertiser (market listing).

createdAtdatetime or nullOptional
Creation time.
updatedAtdatetime or nullOptional
Last change.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
423
Locked Error