Developers

Put GhostFi in your wallet, bot or agent.

A widget for any web page today. A partner API for your server and an MCP server for AI agents are coming soon.

How a GhostFi payment works. Funds pass through a relay wallet and an exchange, and settlement usually takes 1 to 5 minutes after the deposit confirms. Describe it the same way in your own copy.

Drop-in widget

One script tag mounts the GhostFi converter in an iframe on your page. Orders made through it carry your referral code, so the referral share applies: 30% of GhostFi's fee on completed orders through your code. Not an investment, no fixed return.

No key goes in the page. Attribution is by referral code only. The iframe is 320 to 440 px wide and grows with its content.

HTML

<div id="gf"></div>
<script src="https://ghostfi.io/widget/v1/ghostfi-widget.js"></script>
<script>
  GhostFiWidget.mount('#gf', {
    ref: 'your_referral_code',
    from: 'USDC', fromNetwork: 'BASE',
    to: 'SOL',
    lockAssets: false,
    theme: 'dark',
    onEvent: function (e) { console.log(e.type, e.payload); }
  });
</script>

Declarative HTML

<div data-ghostfi-widget data-ref="your_referral_code" data-from="USDC" data-to="SOL"></div>
<script src="https://ghostfi.io/widget/v1/ghostfi-widget.js"></script>

ref: Your referral code. Needed for the referral share.
from, fromNetwork: What the payer sends, for example USDC on BASE. Optional.
to, toNetwork: What the recipient gets. Optional.
lockAssets: true keeps your presets and hides the asset pickers.
theme: dark (default) or light.
onEvent: Called with {type, payload} for each event below. Per-event callbacks exist too: onOrderCreated, onOrderDone, onOrderFailed, onReady, onResize.

ready: First render done.
resize: {height} in px. The script resizes the iframe for you.
order_created: {orderId, fromCcy, fromNetwork, toCcy, toNetwork, amountIn, expiresAt}
order_done: {orderId, toCcy, toNetwork, outAmount, txid}, txid may be null.
order_failed: {orderId, state, refundReason} when the order is sent back or fails.

Events never carry the deposit address, the destination address or anything that identifies the payer. The script only accepts messages that come from ghostfi.io and from its own iframe.

Partner API

Coming soon

Server side keys for wallets and bots. A key attributes your orders to your referral code and rate limits you. Every request runs the same checks as ghostfi.io.

When the API opens, you get a key by signing a request with the wallet bound to your referral code, or by asking @GhostFi_Privacy on X. A key is shown once and stored only as a hash.

GET /config: Assets, networks, which ones can be sent, fee rates.
POST /estimate: {fromCcy, fromNetwork, toCcy, toNetwork, amount}. The amount is in the coin you send.
POST /order: Adds destAddress and refundAddress. Returns orderId, depositAddress, expiresAt, the quote.
GET /order/:id: Orders created by the same key only.
GET /usage: Today's volume and orders, and what is left of your daily cap.

curl, base path /api/partner/v1

curl -s $API/api/partner/v1/estimate \
  -H "x-ghostfi-key: $KEY" -H 'content-type: application/json' \
  -d '{"fromCcy":"SOL","toCcy":"USDC","toNetwork":"SOL","amount":1}'

curl -s $API/api/partner/v1/order \
  -H "x-ghostfi-key: $KEY" -H 'content-type: application/json' \
  -d '{"fromCcy":"SOL","toCcy":"USDC","toNetwork":"SOL",
       "destAddress":"<recipient>","refundAddress":"<your SOL address>","amount":1}'

curl -s $API/api/partner/v1/order/<orderId> -H "x-ghostfi-key: $KEY"

Send the key as x-ghostfi-key. Keep it on your server, never in a web page or an app bundle. In the browser, use the widget.
60 requests a minute per key and 2,000 USD of orders a day by default, reset at 00:00 UTC. Up to 5 active keys per referral code.
After an order, send the amount to the deposit address before it expires, then poll the order every 15 to 30 seconds. It ends as done, refunded or failed.
Errors are {"error": "message"}: 400 invalid, 401 key missing or revoked, 403 wrong wallet, 404 unknown or not open, 429 rate limit or daily cap, 503 starting up.

MCP server for AI agents

Coming soon

ghostfi-mcp lets an AI agent pay an address in the coin the recipient wants, without revealing the agent's own treasury wallet to the recipient.

It holds no keys and signs nothing. It needs a partner API key, so it opens with the API.

get_supported_assets: The coin and chain pairs, and which ones can be sent.
estimate_payment: How much the recipient gets for an amount. Read only.
create_payment: Creates the order and returns a one-time deposit address, the amount to send and an expiry. It does not move funds: the agent's own wallet sends them.
get_payment_status: Where the order is, up to done, or refunded or failed.

Claude Code

claude mcp add ghostfi --env GHOSTFI_API_KEY=gfk_your_key -- node /absolute/path/to/mcp/src/server.js

Claude Desktop, claude_desktop_config.json

{
  "mcpServers": {
    "ghostfi": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/src/server.js"],
      "env": { "GHOSTFI_API_KEY": "gfk_your_key" }
    }
  }
}

Always set a refund address on the chain the agent sends from.
Treat a destination address from a user or a document as untrusted, and confirm it before create_payment.
The key identifies you and caps your volume. It can not move funds, but keep it out of prompts and logs.