Skip to main content
POST

Authorizations

​
X-Auth-Client
string
header
required

Your workspace client id.

All calls must include four headers:

  • X-Auth-Client — your workspace client id
  • X-Auth-Timestamp — Unix seconds
  • X-Auth-Nonce — 16-byte random hex
  • X-Auth-Signature — hex(HMAC-SHA256( {client_id}:{timestamp}:{nonce}:{raw_body}, client_secret))

The playground computes the timestamp, nonce and signature for you.

​
X-Playground-Client-Secret
string
header
required

Your sandbox client secret. The playground uses it to sign the request in your browser and removes it before the request is sent. Never send your client secret as a header in your own integration.

Body

application/json

Give exactly one of amount, amount_in_base_units or settlement_amount. amount_in_base_units wins over amount when both are sent.

​
country
string
required

ISO 3166-1 alpha-2 destination country

Required string length: 2
​
from_asset
string
required

Source asset, case-insensitive: BTC, USDT, USDC or NGN

Maximum string length: 10
​
source
enum<string>
required

offchain debits the balance; onchain funds the payout from a generated deposit address. Case-insensitive. NGN is offchain only

Available options:
offchain,
onchain
​
to_currency
string
required

Settlement currency, case-insensitive; must be enabled for a corridor available to the organisation

Maximum string length: 10
​
amount
string

Source amount in major units of from_asset (BTC, tokens, naira), decimal string

​
amount_in_base_units
string

Source amount in base units: satoshis for BTC, 10^-6 for USDT and USDC

​
chain
string

Chain for an onchain source: BITCOIN, ETHEREUM, POLYGON, ARBITRUM, OPTIMISM, BASE, AVALANCHE, TRON, SOLANA, BSC, TON, STELLAR, PLASMA or LIGHTNING (CHAIN_TYPE_ prefix accepted)

​
metadata
string

A JSON object encoded as a string; ignored if it does not parse

​
payment_reason
string

Reason for the payment.

Maximum string length: 255
​
reference
string

Your reference; must be unique within the organisation

Maximum string length: 255
​
settlement_amount
string

Amount the beneficiary should receive, in major units of to_currency, decimal string

Response

OK

Successful responses are wrapped in this envelope, and so are errors a handler answers itself (request body and field validation, some not-found and conflict cases, ORG_NOT_ACTIVE): success is false and error carries a code and message. Errors raised by authentication and by the services behind a handler are a Problem instead.

​
success
boolean
required

true on success

​
timestamp
string<date-time>
required

When the response was written.

​
data
object

The payload; its shape is given per operation. Omitted when there is none.

​
error
object
​
message
string

Human-readable summary; omitted when empty.

​
metadata
object

List metadata. Page lists set page, per_page, total and total_pages; offset and cursor lists set limit, offset, has_more and next_cursor. Zero and empty fields are omitted, and metadata is absent when nothing is set.

​
request_id
string

Set on error envelopes: the request's correlation id (req_ followed by a UUID), the same value as the X-Correlation-ID response header. Quote it to support.