Convert received funds
A deposit route gives a payer a stable wire reference. When a wire quoting that reference arrives, the platform holds it as the organisation's unconverted fiat and, if the destination wallet can receive it, mints tokens straight away. This page walks the other path: the wallet has no trustline yet, so the delivery is refused and the fiat stays available to convert. The organisation then adds the trustline and delivers the tokens with an on-chain transfer.
Every request runs in CI against an in-process core on FakeChain, so a response that stops matching its # expect line fails the build.
Register and prove the wallet
Create the destination wallet and prove control of it, as in the mint guide. It has no trustline yet, which is what makes the standing delivery wait.
POST /v1/counterparties
authorization: Bearer {{KEY}}
idempotency-key: {{uuid}}
content-type: application/json
{
"type": "stellar_wallet",
"address": "{{WALLET_ADDRESS}}",
"label": "convert guide"
}
# expect 201
# save CPTY = $.id
# save CHALLENGE = $.ownership_proof.challenge_xdr
# sign SIGNED_CHALLENGE = CHALLENGE
POST /v1/counterparties/{{CPTY}}/ownership-proof
authorization: Bearer {{KEY}}
idempotency-key: {{uuid}}
content-type: application/json
{
"signed_challenge_xdr": "{{SIGNED_CHALLENGE}}"
}
# expect 200
Create a deposit route
POST /v1/deposit-routes creates a route to an active wallet. The response's deposit_instructions.wire.reference is the reference a payer quotes.
POST /v1/deposit-routes
authorization: Bearer {{KEY}}
idempotency-key: {{uuid}}
content-type: application/json
{
"destination": { "type": "stellar", "counterparty_id": "{{CPTY}}" },
"label": "convert guide"
}
# expect 201
# save ROUTE = $.id
# save ROUTE_REFERENCE = $.deposit_instructions.wire.reference
Send a wire to the route
POST /v1/sandbox/fiat-deposits records the inbound wire. Because the wallet has no trustline, the standing mint's delivery is refused and the fiat is held as the organisation's unconverted balance instead.
POST /v1/sandbox/fiat-deposits
authorization: Bearer {{KEY}}
idempotency-key: {{uuid}}
content-type: application/json
{
"reference": "{{ROUTE_REFERENCE}}",
"amount": "25.00",
"currency": "USD"
}
# expect 201
Add the trustline
Now sponsor the wallet's trustline, exactly as in the mint guide.
POST /v1/counterparties/{{CPTY}}/sponsored-trustline
authorization: Bearer {{KEY}}
idempotency-key: {{uuid}}
content-type: application/json
{}
# expect 200
# save TRUSTLINE_HASH = $.hash
# save TRUSTLINE_ENVELOPE = $.envelope_xdr
# sign SIGNED_TRUSTLINE = TRUSTLINE_ENVELOPE
POST /v1/counterparties/{{CPTY}}/sponsored-trustline/submit
authorization: Bearer {{KEY}}
idempotency-key: {{uuid}}
content-type: application/json
{
"hash": "{{TRUSTLINE_HASH}}",
"signed_envelope_xdr": "{{SIGNED_TRUSTLINE}}"
}
# expect 200
Check the unconverted balance
GET /v1/accounts shows the token balances for each asset the organisation holds. balances.available_to_convert is the fiat the organisation has received but not yet delivered as tokens. It is non-zero, because the refused standing mint left the wire credited.
GET /v1/accounts
authorization: Bearer {{KEY}}
# expect 200
Deliver the tokens on chain
Create an on-chain transfer with source.type balance on POST /v1/transfers. Its amount is in token units, and it can be no larger than available_to_convert.
POST /v1/transfers
authorization: Bearer {{KEY}}
idempotency-key: {{uuid}}
content-type: application/json
{
"source": { "type": "balance", "asset": "USDX" },
"destination": { "type": "stellar", "asset": "USDX", "counterparty_id": "{{CPTY}}" },
"amount": "10.0000000"
}
# expect 201
# save TRANSFER = $.id
Read the transfer back. It is completed once the tokens have been delivered to the wallet.
GET /v1/transfers/{{TRANSFER}}
authorization: Bearer {{KEY}}
# expect 200