Transfer NFTs via API: Steps, Parameters and Pitfalls
How an NFT transfer API works: ownership checks, request parameters, gas, signing, confirmation and common errors on Ethereum and Solana, with a practical checklist.
An NFT transfer API lets your backend move a token from one wallet to another with a single HTTP request, instead of your team writing contract calls, signing transactions and managing nodes by hand. Under the hood, every transfer is still an on-chain transaction: the API’s job is to verify ownership, build the right call for the token standard, estimate fees, sign, broadcast and then tell you what happened. This guide walks through each of those steps, the parameters every request needs, and the errors that cost developers the most time.
TL;DR
- An NFT transfer changes the owner recorded in a token contract. On Ethereum-style chains it is a call to
transferFromorsafeTransferFrom; on Solana it is a token or Metaplex instruction. - A request needs four things: the sender wallet, the recipient address, the contract (or mint) address, and the token ID. ERC-1155 also needs an amount.
- Check ownership before you send, estimate fees before you sign, and confirm success from the chain (receipt and Transfer event), not from the HTTP response alone.
- The most common failures are wrong chain, recipient contracts that cannot receive NFTs, missing native gas and stale ownership.
- A unified API removes the per-chain plumbing. Ours also covers webhooks for confirmation, so you do not poll.
Table of Contents
- What an NFT transfer API actually does
- Which standards and chains a transfer API can cover
- How to transfer an NFT through an API, step by step
- What a transfer request needs
- Fees: estimating and paying
- Security precautions
- Common errors and what they mean
- Confirming transfers with webhooks instead of polling
- Our perspective
- Moving NFTs with Chaingateway
- A pre-launch checklist
- FAQ
- Sources
What an NFT transfer API actually does
An NFT is a record in a smart contract (or, on Solana, a token account) that says which address owns which token. Transferring it means changing that record, and only the owner or someone the owner has authorized can do that.
The ERC-721 standard defines this at the contract level. Each token is identified by a token ID, and a transfer moves ownership from one address to another when it is initiated by the owner, an approved address or an operator. The contract then emits a Transfer event, which is the signal most indexers and notification systems listen for.
An API sits on top of that. A good one handles five jobs for you:
- Ownership verification: confirm the sending wallet currently owns the token.
- Call construction: encode the right function for the standard and chain.
- Fee estimation: work out gas or network fees and check the wallet can pay them.
- Signing and broadcasting: sign with the wallet’s key and submit the transaction.
- Status reporting: return a transaction hash and tell you when the transfer is final.
The alternative is running your own node, holding web3 libraries per chain and writing the encoding yourself. That works for one chain and one collection. It gets expensive when you add a second network.
Which standards and chains a transfer API can cover
Not every NFT is the same kind of object, so an API must speak more than one dialect.
| Standard / model | Chains | How transfer works |
|---|---|---|
| ERC-721 | Ethereum, Polygon, Arbitrum and other EVM chains | One token ID per token; transferFrom or safeTransferFrom |
| ERC-1155 | Ethereum and EVM chains | Multi-token contract; transfer includes an amount per token ID, with batch transfers |
| SPL token with supply one + Metaplex metadata | Solana | Token program transfer; metadata stored separately |
ERC-1155 is worth a closer look if you handle game items or tickets. One contract holds both fungible and non-fungible types, its interface includes single and safe batch transfers, and each transfer carries an amount for the token ID. A token with a supply of one behaves as a classic NFT, but an edition with a supply of 500 is a different case: you must send an amount, not just an ID.
Solana works differently. It does not typically deploy a separate contract per collection. Its Token Program is used with a mint supply of one, while Metaplex Token Metadata holds the NFT details. So on Solana you transfer by mint address, not by contract plus token ID, and you should expect the recipient to need a token account for that mint.
When you evaluate any provider, ask which of these three models it supports on which chains. Chaingateway’s Blockchain API covers Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Chain and Arbitrum, and supports the major token standards including ERC-721, so the same integration pattern applies across the networks you add later.
How to transfer an NFT through an API, step by step
The flow is the same regardless of provider. What differs is how much of it you write yourself.
1. Verify ownership
Before building a transaction, confirm the sender actually owns the token. For ERC-721 this means asking the contract who owns the token ID. For ERC-1155 it means checking the balance of that ID for the address. For Solana, check the token account holding the mint.
Do this immediately before sending, not from a cached database row. NFTs can be sold or moved in the seconds between your last sync and your request, and a transfer from a wallet that no longer owns the token will simply fail and still cost fees in some failure modes.
2. Check authorization
The standard allows the owner, an approved address or an operator to initiate a transfer. If your service moves NFTs out of user-owned wallets that you do not control, you need an approval first. If your service holds the keys for wallets it created (as in custodial flows), the sending wallet is the owner and no approval is needed.
3. Build and estimate
Choose the function and encode the arguments. Then estimate the fee. On EVM chains that means a gas limit multiplied by a gas price; on Solana it is a small per-signature fee plus, possibly, rent for a new token account. An API with automatic gas estimation does this for you, so you do not hard-code a gas limit that fails when the recipient is a contract with extra logic.
Also confirm the wallet holds enough of the native coin. An address with ten NFTs and zero ETH cannot move any of them.
4. Sign and broadcast
The transaction must be signed by the owner’s private key. Either you sign locally and submit the raw transaction, or the API signs for a wallet it manages. Managed wallets are simpler for backend flows, since your servers never handle raw keys.
5. Confirm
A transaction hash means the network accepted your submission, not that the transfer succeeded. Wait for a receipt showing success, and for the Transfer event with the expected sender, recipient and token ID. For high-value NFTs, wait for several confirmations before you update your own database or release anything in exchange.
What a transfer request needs
Whatever the provider’s field names, the request carries the same information.
| Parameter | Why it is needed | Notes |
|---|---|---|
| Chain / network | The same address exists on many EVM chains | Mainnet vs testnet is the first thing to check when a token “vanishes” |
| Sender wallet | Identifies who signs and pays | Must own the token and hold native gas |
| Recipient address | Destination | Validate format and checksum; never accept free text without checks |
| Contract or mint address | Identifies the collection | Contract on EVM, mint on Solana |
| Token ID | Identifies the individual token | Not used on Solana, where the mint is the token |
| Amount | Quantity to move | Required for ERC-1155; one for ERC-721 |
| Fee settings | Gas limit and price, or priority fee | Let the API estimate unless you have a reason not to |
| Idempotency or reference | Prevents double sends on retry | Store your own reference against the transaction hash |
That last row matters more than it looks. If your request times out, you do not know whether the transaction was broadcast. Retrying blindly can send a second transaction, which for a unique NFT will simply fail, but for an ERC-1155 edition can move extra copies. Look up the earlier attempt first.
Fees: estimating and paying
On EVM networks the sender pays gas in the chain’s native coin, and the cost varies with network congestion and the complexity of the call. A plain transferFrom is cheap compared with a mint or a marketplace sale, but a recipient contract with a heavy receiver function can raise it.
Practical rules:
- Estimate immediately before sending and add a modest buffer instead of using a fixed number.
- Keep a minimum native balance on every wallet that sends NFTs, and alert when it drops below it.
- If you transfer on behalf of users, decide up front who pays: you (top up the wallet) or the user (deduct from a balance). Surprises here become support tickets.
- On Solana, remember the recipient may need a new token account, which has a one-time cost.
Security precautions
NFT transfers are irreversible. There is no chargeback and no support desk on-chain, so the safeguards live in your code.
Protect the signing path. Authenticate every API call. Chaingateway signs requests with HMAC, so a request that was altered in transit or sent by someone without the secret is rejected. Keep the secret in a vault, rotate it, and never ship it in a browser or mobile app.
Validate the recipient. Check address format and chain. Offer a confirmation step for high-value items. Where policy requires it, screen addresses before sending.
Mind receiver contracts. The ERC-721 specification describes safeTransferFrom as checking, when the destination is a contract, that it implements the receiver interface, and reverting if it does not. Using the safe variant protects you from locking a token in a contract that cannot move it. The plain transferFrom leaves that responsibility to the caller.
Limit exposure. Keep a hot wallet with only the NFTs needed for near-term transfers and the rest in a more restricted wallet. Apply per-request and daily limits in your own layer.
Log everything. Record who requested the transfer, the parameters, the hash and the result. When a customer disputes a transfer, the chain proves what happened, and your logs prove who asked for it.
Common errors and what they mean
| Symptom | Likely cause | Fix |
|---|---|---|
| Transaction reverts | Sender does not own the token, or is not approved | Re-check ownership and approval just before sending |
| Reverts only for some recipients | Recipient is a contract without a receiver function | Use another address, or confirm the contract supports NFTs |
| ”Insufficient funds” | No native coin for fees | Top up the sending wallet |
| Transaction stuck pending | Gas price too low or nonce gap | Replace with a higher fee using the same nonce |
| Token not visible at recipient | Wrong network, or metadata not refreshed | Verify the chain and the Transfer event; wallets may cache |
| Wrong quantity moved | ERC-1155 amount mishandled | Always pass an explicit amount and verify the balance afterward |
Most of these are caught by two habits: checking ownership and balance first, and treating the on-chain receipt as the only proof of success.
Confirming transfers with webhooks instead of polling
Polling a transaction hash every few seconds works in a prototype and wastes requests in production. Webhooks flip the model: the provider calls your endpoint when the transfer is mined, with decoded data on sender, recipient and token. Verify the signature on each incoming call, respond quickly, and process events idempotently, because deliveries can be repeated. If you want to understand what such events look like at the log level, our walkthrough of the ERC-20 Transfer event covers the structure and topics, and the ERC-721 event follows the same pattern with the token ID indexed.
Our perspective
Most teams underestimate NFT transfers because the happy path is one function call. The work is in everything around it: which chain, whose gas, what happens on retry, how you learn the result. We built Chaingateway so a developer does not carry that surface area. One REST API replaces chain-specific endpoints and your own nodes, responses arrive pre-decoded so you are not parsing logs by hand, gas is estimated automatically, and requests are HMAC-signed.
Our advice is to design for the failure cases first. Decide who pays fees, what counts as confirmed, and how a retry is recognized, and the transfer call itself becomes the easy part. For broader context on where each kind of provider fits, see our comparison of blockchain API types.
— Bitblade
Moving NFTs with Chaingateway
If you are building an app that creates wallets, sends tokens and NFTs, and reacts to on-chain events, Chaingateway’s Blockchain API gives you one integration for Ethereum, Solana, Polygon, BNB Chain, Arbitrum, Tron and Bitcoin. Paired with webhook notifications, you can send a transfer and be told when it lands. Plans start at €49 per month (Plus), with Pro at €99, Premium at €249 and Enterprise at €499 per month; annual billing is €490, €990, €2490 and €4990 respectively. See the pricing page for what each plan includes, and start with the free trial to test transfers on your own chain.
If your stack leans on a specific network, the dedicated pages for the Ethereum API and the Solana API show how token sending works on each.
A pre-launch checklist
Before you let real users trigger NFT transfers, run through this list on a testnet first:
- Transfer a token you own to a normal wallet and confirm the receipt and the
Transferevent. - Transfer to a contract that cannot receive NFTs and confirm your code surfaces the failure.
- Attempt a transfer from a wallet with no native coin and confirm the error is clear.
- Send the same request twice and confirm your idempotency check stops the second.
- Kill your webhook endpoint for a minute, restore it and confirm events are not lost or double-processed.
- Review who can call the endpoint, with what limits, and where the secret is stored.
Sources
Recommended
Frequently asked questions
Yes. A hosted blockchain API connects to the nodes for you, builds and broadcasts the transaction and returns the hash. You still need to manage the wallet’s keys or use a managed wallet, and keep native coin available for fees.
Both change ownership under ERC-721. The safe version also checks that a contract recipient implements the receiver interface and reverts otherwise, which prevents tokens from getting stuck, according to the ERC-721 specification. For automated flows, the safe version is usually the better default.
Yes, in practice. ERC-1155 transfers carry an amount per token ID and support batch transfers, as the ERC-1155 standard describes. Your request must include the quantity, and you should verify the balance afterward.
Check the transaction receipt for success and look for the matching Transfer event with the right sender, recipient and token ID. A webhook can deliver that to your backend as soon as it is mined, so you do not need to poll.
Not by you. Only the new owner can send it back. That is why you should validate addresses, confirm the chain and add a confirmation step for valuable tokens before sending.
Ready to build this yourself? Get your API key — 7-day trial, no card required — or see the Blockchain API for the full endpoint reference.