واجهة برمجة تطبيقات التبادلات 📝

مقدمة

واجهة برمجة تطبيقات التبادلات هي واجهة المبادلة الأساسية لـ p3p. استخدمها لاكتشاف ما يمكن تداوله، والحصول على أفضل عرض سعر عبر كل مصدر سيولة مجمع، وقفل ذلك العرض في مبادلة على السلسلة، وتتبعها حتى اكتمالها.

تتطلب جميع نقاط النهاية أدناه رأس مطور api-key. سجّل كشريك على p3p.xyz للحصول عليه.

http

api-key: YOUR_P3P_API_KEY

نقاط النهاية

1. جلب السلاسل 2. جلب الرموز 3. جلب الأسعار 4. الحصول على عرض سعر التبادل 5. إنشاء تبادل 6. التحقق من حالة التبادل التحقق من حالة تبادلات متعددة

1. جلب السلاسل

GET /chains api-key مطلوب

يعيد كل سلسلة مفعلة حالياً على p3p.

curlfetch

bash

curl https://api.p3p.xyz/chains \
  -H "api-key: YOUR_P3P_API_KEY"

const chains = await fetch("https://api.p3p.xyz/chains", {
  headers: { "api-key": "YOUR_P3P_API_KEY" },
}).then((r) => r.json());

json

{
  "status": 200,
  "message": "ok",
  "data": [
    {
      "id": 0,
      "key": "btc",
      "name": "Bitcoin",
      "display": "BTC Chain",
      "color": "#F7931A",
      "logo": "",
      "icon": "token:btc",
      "explorer": {
        "address": "https://mempool.space/address/%s",
        "tx": "https://mempool.space/tx/%s"
      },
      "website": "https://bitcoin.org",
      "vm": "BVM",
      "validation": [
        "^(1[1-9A-HJ-NP-Za-km-z]{25,34}|3[1-9A-HJ-NP-Za-km-z]{25,34}|bc1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]{8,87})$"
      ],
      "defaults": ["btc"],
      "tags": ["bitcoin", "btc", "xbt", "satoshi"],
      "enabled": true
    },
    {
      "id": 1,
      "key": "eth",
      "name": "Ethereum",
      "display": "ETH Chain",
      "color": "#627EEA",
      "logo": "",
      "icon": "token:eth",
      "explorer": {
        "address": "https://etherscan.io/address/%s",
        "tx": "https://etherscan.io/tx/%s"
      },
      "website": "https://ethereum.org",
      "vm": "EVM",
      "validation": [
        "^(0x)[0-9A-Fa-f]{40}$"
      ],
      "defaults": ["eth", "usdt", "usdc", "dai"],
      "tags": ["ethereum", "eth", "eht", "vitalik"],
      "enabled": true
    }
  ]
}

2. جلب الرموز

GET /tokens api-key مطلوب

يعيد الرموز المفعلة مجمعة حسب السلسلة.

bash

curl https://api.p3p.xyz/tokens \
  -H "api-key: YOUR_P3P_API_KEY"

json

{
  "eth": [
    { "key": "eth", "name": "Ether", "symbol": "ETH", "decimals": 18, "rate": "3421.8", "address": "", "native": true, "enabled": true },
    { "key": "usdt", "name": "Tether", "symbol": "USDT", "decimals": 6, "rate": "1.0", "address": "0xdac17f958d2ee523a2206206994597c13d831ec7", "native": false, "enabled": true }
  ],
  "ton": [
    { "key": "ton", "name": "Toncoin", "symbol": "TON", "decimals": 9, "rate": "5.23", "address": "", "native": true, "enabled": true },
    { "key": "usdt", "name": "USDT (TON)", "symbol": "USDT", "decimals": 6, "rate": "1.0", "address": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", "native": false, "enabled": true }
  ]
}

3. جلب الأسعار

GET /rates api-key مطلوب

يعيد أسعار السوق المرجعية الحية لكل أصل مدعوم، مأخوذة من Oracle على السلسلة.

bash

curl https://api.p3p.xyz/rates \
  -H "api-key: YOUR_P3P_API_KEY"

json

{
  "btc": 98234.56,
  "eth": 3421.8,
  "ton": 5.23,
  "usdt": 1.0,
  "usdc": 1.0,
  "sol": 142.35
}

4. الحصول على عرض سعر التبادل

POST /exchange/rate api-key مطلوب

تجميع الأسعار من كل مصدر سيولة نشط وإعادة الأفضل (أو جميعها).

الجسم

الحقل	النوع	مطلوب	الوصف
`chain_from`	string	نعم	مفتاح السلسلة المصدر
`token_from`	string	نعم	مفتاح الرمز المصدر
`amount_from`	string	نعم	الكمية بوحدات العرض
`chain_to`	string	نعم	مفتاح سلسلة الوجهة
`token_to`	string	نعم	مفتاح رمز الوجهة
`opts.best`	boolean	لا	الترتيب حسب أفضل سعر (افتراضي)
`opts.fastest`	boolean	لا	الترتيب حسب أسرع سعر بدلاً من الأفضل
`opts.partner_id`	string	لا	معرف شريكك أو المحفظة المسجلة (كسب الإيرادات)

curlfetch

bash

curl -X POST https://api.p3p.xyz/exchange/rate \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_P3P_API_KEY" \
  -d '{
    "chain_from": "eth",
    "token_from": "eth",
    "amount_from": "0.1",
    "chain_to": "ton",
    "token_to": "ton",
    "opts": { "best": true }
  }'

const rate = await fetch("https://api.p3p.xyz/exchange/rate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "api-key": "YOUR_P3P_API_KEY",
  },
  body: JSON.stringify({
    chain_from: "eth",
    token_from: "eth",
    amount_from: "0.1",
    chain_to: "ton",
    token_to: "ton",
    opts: { best: true },
  }),
}).then((r) => r.json());

json

{
  "type": "crypto",
  "path_from": "eth.eth",
  "path_to": "ton.ton",
  "amount_from": "0.1",
  "amount_to": "342.18",
  "direction": "exact_input",
  "amount_from_unit": 0.1,
  "amount_to_unit": 342.18,
  "rate": "3421.8",
  "impact": "0.01",
  "duration": 90,
  "boosted": false
}

5. إنشاء تبادل

POST /exchange/create api-key مطلوب

اقفل سعراً، أنشئ تبادلاً واستلم عنوان إيداع.

الجسم

الحقل	النوع	مطلوب	الوصف
`chain_from`	string	نعم	مفتاح السلسلة المصدر
`token_from`	string	نعم	مفتاح الرمز المصدر
`amount_from`	string	نعم	الكمية بوحدات العرض
`chain_to`	string	نعم	مفتاح سلسلة الوجهة
`token_to`	string	نعم	مفتاح رمز الوجهة
`wallet_to`	string	نعم	عنوان المستلم على سلسلة الوجهة
`wallet_refund`	string	لا	عنوان الاسترداد إذا لم تكتمل المبادلة
`wallet_from`	string	لا	عنوان المصدر للمستخدم (بعض السلاسل تحتاجه)
`opts.best`	boolean	لا	الترتيب حسب أفضل سعر (افتراضي)
`opts.fastest`	boolean	لا	الترتيب حسب أسرع سعر بدلاً من الأفضل
`opts.partner_id`	string	لا	معرف شريكك أو المحفظة المسجلة (كسب الإيرادات)

curlfetch

bash

curl -X POST https://api.p3p.xyz/exchange/create \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_P3P_API_KEY" \
  -d '{
    "chain_from": "eth", "token_from": "eth", "amount_from": "0.1",
    "chain_to":   "ton", "token_to":   "ton",
    "wallet_to":     "UQAbc...XYZ",
    "wallet_refund": "0xRefund...address",
    "opts": { "partner_id": "P3_YOURPARTNERID" }
  }'

const exchange = await fetch("https://api.p3p.xyz/exchange/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "api-key": "YOUR_P3P_API_KEY",
  },
  body: JSON.stringify({
    chain_from: "eth",
    token_from: "eth",
    amount_from: "0.1",
    chain_to: "ton",
    token_to: "ton",
    wallet_to: "UQAbc...XYZ",
    wallet_refund: "0xRefund...address",
    opts: { partner_id: "P3_YOURPARTNERID" }, 
  }),
}).then((r) => r.json());

json

{
  "created_at": "2026-05-24T10:30:00Z",
  "id": "ex_8f4c2a...",
  "type": "crypto",
  "chain_from": "eth",
  "token_from": "eth",
  "amount_from": "0.1",
  "chain_to": "ton",
  "token_to": "ton",
  "amount_to": "342.18",
  "amount_to_unit": 342.18,
  "wallet_refund": "0xRefund...address",
  "wallet_from": "",
  "wallet_to": "UQAbc...XYZ",
  "deposit_address": "0xDepositAddressGeneratedForYou",
  "rate": "3421.8",
  "impact": "0.01",
  "duration": 90
}

لتبادلات الشركاء (عند استخدام رأس api-key): تعيد الاستجابة hash بدلاً من id:

json

{
  "created_at": "2026-05-24T10:30:00Z",
  "hash": "A7K2M9X5B3C1D8F4",
  "type": "crypto",
  "chain_from": "eth",
  "token_from": "eth",
  "amount_from": "0.1",
  "chain_to": "ton",
  "token_to": "ton",
  "amount_to": "342.18",
  "amount_to_unit": 342.18,
  "wallet_to": "UQAbc...XYZ",
  "deposit_address": "0xDepositAddressGeneratedForYou",
  "rate": "3421.8",
  "impact": "0.01",
  "duration": 90
}

أرسل amount_from من token_from من محفظتك إلى deposit_address لبدء المبادلة. تتبع التقدم باستخدام التحقق من حالة التبادل أدناه.

تبادلات الشركاء خاصة

تبادلات الشركاء (المحددة بواسطة hash) لا يمكن الوصول إليها إلا بتمرير الهاش كمعرف مع رأس api-key. لا يمكن الاستعلام عنها بمعرف المعاملة العادي.

نافذة الإيداع

يجب أن يطابق الإيداع amount_from تماماً ويصل خلال ~6 دقائق. بعد انتهاء المهلة يمكنك إعادة المحاولة باستخدام ?bump=true على نقطة نهاية الحالة.

6. التحقق من حالة التبادل

GET /check/:txId api-key مطلوب

احصل على الحالة الحالية لعملية تبادل أو فاتورة واحدة.

الاستعلام	النوع	الوصف
`bump`	boolean	إذا كان `true`، يعيد محاولة تبادل متوقف/منتهي

bash

curl https://api.p3p.xyz/check/ex_8f4c2a... \
  -H "api-key: YOUR_P3P_API_KEY"

json

{
  "id": "ex_8f4c2a...",
  "created_at": "2026-05-24T10:30:00Z",
  "status": "exchanging",
  "type": "internal",
  "invoice": false,
  "chain_from": "eth",
  "token_from": "eth",
  "amount_from": "0.1",
  "chain_to": "ton",
  "token_to": "ton",
  "amount_to": "342.18",
  "amount_to_unit": 342.18,
  "wallet_to": "UQAbc...XYZ",
  "deposit_address": "0xDepositAddressGeneratedForYou",
  "checkpoint": 3,
  "checkpoints": 5
}

قيم الحالة

الحالة	المعنى
`new`	في انتظار إيداع المستخدم
`deposited`	تم اكتشاف الإيداع، جارٍ التجهيز للمبادلة
`processing`	تم إرسال المبادلة إلى مصدر السيولة، في انتظار التأكيد
`exchanging`	تأكيد المبادلة، جارٍ تحويل الأموال
`complete`	تم — استلم المستلم الأموال
`timeout`	انتهت مهلة الإيداع؛ استدع مع `?bump=true` لإعادة التعيين والمحاولة
`error`	واجه التبادل خطأ؛ استدع مع `?bump=true` لإعادة المحاولة
`expired`	انتهت صلاحية التبادل ولا يمكن إعادة محاولته

إعادة Bump

إذا انتهت مهلة الصفقة (لم يتم اكتشاف إيداع خلال نافذة الإيداع)، استدع نقطة النهاية مرة أخرى باستخدام ?bump=true لإعادة تعيين النافذة:

bash

curl "https://api.p3p.xyz/check/ex_8f4c2a...?bump=true" \
  -H "api-key: YOUR_P3P_API_KEY"

تبادلات الشركاء (المنشأة برأس api-key) يمكن الاستعلام عنها بتمرير hash كمعرف. إذا كان رأس api-key موجوداً، يحاول النظام تلقائياً مطابقته كـ hash أولاً:

bash

# استخدام api-key الشريك — بحث بالهاش
curl https://api.p3p.xyz/check/A7K2M9X5B3C1D8F4 \
  -H "api-key: YOUR_PARTNER_API_KEY"

json

{
  "hash": "A7K2M9X5B3C1D8F4",
  "created_at": "2026-05-24T10:30:00Z",
  "status": "complete",
  "type": "internal",
  "invoice": false,
  "chain_from": "eth",
  "token_from": "eth",
  "amount_from": "0.1",
  "chain_to": "ton",
  "token_to": "ton",
  "amount_to": "342.18",
  "amount_to_unit": 342.18,
  "wallet_to": "UQAbc...XYZ",
  "deposit_address": "0xDepositAddressGeneratedForYou",
  "checkpoint": 5,
  "checkpoints": 5
}

صيغة الهاش

افتراضياً، تتكون الهاشات من 40 حرفاً وأرقاماً (a-z, A-Z, 0-9). يمكن للشركاء تخصيص الصيغة عبر لوحة تحكم الشريك.

7. التحقق من تبادلات متعددة

POST /check api-key مطلوب

تحقق من عدة صفقات في استدعاء واحد.

الجسم

الحقل	النوع	مطلوب	الوصف
`hashes`	string[]	نعم	مصفوفة معرفات التبادل

bash

curl -X POST https://api.p3p.xyz/check \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_P3P_API_KEY" \
  -d '{ "hashes": ["ex_8f4c2a...", "ex_aa11bb..."] }'

يعيد مصفوفة من كائنات حالة التبادل المضغوطة:

json

[
  {
    "hash": "ex_8f4c2a...",
    "status": "complete",
    "type": "crypto",
    "invoice": false,
    "chain_from": "eth",
    "token_from": "eth",
    "amount_from": "0.1",
    "chain_to": "ton",
    "token_to": "ton",
    "amount_to": "342.18",
    "checkpoint": 4,
    "checkpoints": 4
  },
  {
    "hash": "A7K2M9X5B3C1D8F4",
    "status": "exchanging",
    "type": "crypto",
    "invoice": false,
    "chain_from": "ton",
    "token_from": "usdt",
    "amount_from": "100",
    "chain_to": "eth",
    "token_to": "usdc",
    "amount_to": "99.5",
    "checkpoint": 2,
    "checkpoints": 4
  }
]

واجهة برمجة تطبيقات التبادلات 📝 ​

مقدمة ​

نقاط النهاية ​

1. جلب السلاسل ​

2. جلب الرموز ​

3. جلب الأسعار ​

4. الحصول على عرض سعر التبادل ​

5. إنشاء تبادل ​

6. التحقق من حالة التبادل ​

قيم الحالة ​

إعادة Bump ​

7. التحقق من تبادلات متعددة ​

واجهة برمجة تطبيقات التبادلات 📝

مقدمة

نقاط النهاية

1. جلب السلاسل

2. جلب الرموز

3. جلب الأسعار

4. الحصول على عرض سعر التبادل

5. إنشاء تبادل

6. التحقق من حالة التبادل

قيم الحالة

إعادة Bump

7. التحقق من تبادلات متعددة