Mint from a wire
A mint turns an inbound bank wire into tokens in an organisation's wallet. This page takes the whole flow end to end: register a wallet, prove control of it, sponsor its trustline, create the transfer, read its deposit instructions, simulate the wire, and read the transfer back as completed.
Every request on this page runs in CI against an in-process core on FakeChain, so a response that stops matching its # expect line fails the build. The {{KEY}}, {{uuid}} and {{WALLET_ADDRESS}} placeholders work exactly as in the quickstart: your API key, a fresh idempotency key, and the page's funded Testnet wallet.
Register and prove the wallet
Create a stellar_wallet counterparty with POST /v1/counterparties. The response carries an ownership challenge, and only the wallet's key can sign it. Lines starting with # are directives for the docs runner, not part of the request: # expect is the status the request must return, # save carries a value into a later request, and # sign signs a saved XDR with the page's wallet.
POST /v1/counterparties
authorization: Bearer {{KEY}}
idempotency-key: {{uuid}}
content-type: application/json
{
"type": "stellar_wallet",
"address": "{{WALLET_ADDRESS}}",
"label": "mint guide"
}
# expect 201
# save CPTY = $.id
# save CHALLENGE = $.ownership_proof.challenge_xdr
# sign SIGNED_CHALLENGE = CHALLENGE
Submit the signed challenge with POST /v1/counterparties/{id}/ownership-proof. The wallet becomes active, which is what a later transfer needs.
POST /v1/counterparties/{{CPTY}}/ownership-proof
authorization: Bearer {{KEY}}
idempotency-key: {{uuid}}
content-type: application/json
{
"signed_challenge_xdr": "{{SIGNED_CHALLENGE}}"
}
# expect 200
Sponsor the trustline
An active wallet still needs a trustline to the asset, and the issuer sponsors it. Ask for the offer with POST /v1/counterparties/{id}/sponsored-trustline, co-sign the returned envelope with the wallet key, then submit the hash and the signed envelope together. The offer expires about a minute after it is issued, so keep the signing step close by.
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
Create the transfer and read its instructions
POST /v1/transfers creates a mint when source.type is fiat. The body names the wallet as the destination. The response's deposit_instructions.reference is the wire reference the payer must quote.
POST /v1/transfers
authorization: Bearer {{KEY}}
idempotency-key: {{uuid}}
content-type: application/json
{
"source": { "type": "fiat", "currency": "USD", "rail": "wire" },
"destination": { "type": "stellar", "asset": "USDX", "counterparty_id": "{{CPTY}}" },
"amount": "100.00"
}
# expect 201
# save TRANSFER = $.id
# save REFERENCE = $.deposit_instructions.reference
Read it back with GET /v1/transfers/{id}. It waits in awaiting_funds until a matching wire arrives.
GET /v1/transfers/{{TRANSFER}}
authorization: Bearer {{KEY}}
# expect 200
Simulate the wire
POST /v1/sandbox/fiat-deposits records an inbound wire through the same path as a real bank webhook. Quote the reference so it attributes to the waiting mint.
POST /v1/sandbox/fiat-deposits
authorization: Bearer {{KEY}}
idempotency-key: {{uuid}}
content-type: application/json
{
"reference": "{{REFERENCE}}",
"amount": "100.00",
"currency": "USD"
}
# expect 201
Watch it complete
Read the transfer once more. It is completed once the delivery has been submitted and confirmed on chain.
GET /v1/transfers/{{TRANSFER}}
authorization: Bearer {{KEY}}
# expect 200
The completed transfer carries a stellar_tx_hash; open it in an explorer to see the tokens arrive in the wallet.