API degli Exchange 📝

Introduzione

L'API degli Exchange è la superficie di swap principale di p3p. Usala per scoprire cosa è scambiabile, ottenere la migliore quotazione tra ogni fonte di liquidità aggregata, bloccare quella quotazione in uno swap on-chain e tracciarlo fino al completamento.

Tutti gli endpoint sottostanti richiedono un header api-key di sviluppatore. Registrati come partner su p3p.xyz per ottenerne uno.

http

api-key: YOUR_P3P_API_KEY

Endpoint

1. Ottieni Catene 2. Ottieni Token 3. Ottieni Tassi 4. Quota Tasso di Exchange 5. Crea Exchange 6. Verifica Stato Exchange 7. Verifica Stato Più Exchange

1. Ottieni Catene

GET /chains api-key richiesta

Restituisce ogni catena attualmente abilitata su 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. Ottieni Token

GET /tokens api-key richiesta

Restituisce i token abilitati raggruppati per catena.

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. Ottieni Tassi

GET /rates api-key richiesta

Restituisce i tassi di mercato di riferimento in tempo reale per ogni asset supportato, provenienti da oracoli on-chain.

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. Quota Tasso di Exchange

POST /exchange/rate api-key richiesta

Aggrega i tassi da ogni fonte di liquidità attiva e restituisce il migliore (o tutti).

Body

Campo	Tipo	Richiesto	Descrizione
`chain_from`	string	sì	Chiave catena sorgente
`token_from`	string	sì	Chiave token sorgente
`amount_from`	string	sì	Quantità in unità di visualizzazione
`chain_to`	string	sì	Chiave catena destinazione
`token_to`	string	sì	Chiave token destinazione
`opts.best`	boolean	no	Ordina per miglior tasso (predefinito)
`opts.fastest`	boolean	no	Ordina per tasso più veloce invece del migliore
`opts.partner_id`	string	no	Il tuo ID partner o wallet registrato (guadagna entrate)

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. Crea Exchange

POST /exchange/create api-key richiesta

Blocca un tasso, crea un exchange e ricevi un indirizzo di deposito.

Body

Campo	Tipo	Richiesto	Descrizione
`chain_from`	string	sì	Chiave catena sorgente
`token_from`	string	sì	Chiave token sorgente
`amount_from`	string	sì	Quantità in unità di visualizzazione
`chain_to`	string	sì	Chiave catena destinazione
`token_to`	string	sì	Chiave token destinazione
`wallet_to`	string	sì	Indirizzo destinatario sulla catena di destinazione
`wallet_refund`	string	no	Indirizzo di rimborso se lo swap non può completarsi
`wallet_from`	string	no	Indirizzo sorgente dell'utente (alcune catene ne hanno bisogno)
`opts.best`	boolean	no	Ordina per miglior tasso (predefinito)
`opts.fastest`	boolean	no	Ordina per tasso più veloce invece del migliore
`opts.partner_id`	string	no	Il tuo ID partner o wallet registrato (guadagna entrate)

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
}

Per gli exchange partner (quando si usa il header api-key): La risposta restituisce hash al posto di 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
}

Invia amount_from di token_from dal tuo wallet a deposit_address per avviare lo swap. Traccia il progresso con Verifica Stato Exchange sotto.

Gli exchange partner sono privati

Gli exchange partner (identificati da hash) sono accessibili solo passando l'hash come ID con il tuo header api-key. Non possono essere interrogati per ID di transazione normale.

Finestra di deposito

Il deposito deve corrispondere esattamente a amount_from e arrivare entro ~6 minuti. Dopo il timeout puoi riprovare con ?bump=true sull'endpoint di stato.

6. Verifica Stato Exchange

GET /check/:txId api-key richiesta

Ottieni lo stato attuale di un singolo exchange o fattura.

Query	Tipo	Descrizione
`bump`	boolean	Se `true`, riprova un exchange bloccato/scaduto

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
}

Valori di stato

Stato	Significato
`new`	In attesa del deposito dell'utente
`deposited`	Deposito rilevato, preparazione dello swap
`processing`	Swap inviato alla fonte di liquidità, in attesa di conferma
`exchanging`	Swap confermato, i fondi vengono scambiati
`complete`	Fatto — il destinatario ha ricevuto i fondi
`timeout`	Finestra di deposito scaduta; chiamare con `?bump=true` per reimpostare e riprovare
`error`	Lo scambio ha riscontrato un errore; chiamare con `?bump=true` per riprovare
`expired`	Lo scambio è scaduto e non può più essere riprovato

Riprova bump

Se un trade va in timeout (nessun deposito rilevato entro la finestra di deposito), chiama nuovamente l'endpoint con ?bump=true per resettare la finestra:

bash

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

Exchange partner (creati con il header api-key) possono essere interrogati passando il hash come ID. Se è presente un header api-key, il sistema tenta automaticamente di abbinarlo come hash prima:

bash

# Usando api-key partner — cerca per hash
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
}

Formato hash

Per impostazione predefinita, gli hash sono 40 caratteri alfanumerici (a-z, A-Z, 0-9). I partner possono personalizzare il formato tramite il Partner Dashboard.

7. Verifica Più Exchange

POST /check api-key richiesta

Verifica più trade in una sola chiamata.

Corpo

Campo	Tipo	Richiesto	Descrizione
`hashes`	string[]	sì	Array di ID di exchange

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..."] }'

Restituisce un array di oggetti di stato exchange minificati:

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
  }
]

API degli Exchange 📝 ​

Introduzione ​

Endpoint ​

1. Ottieni Catene ​

2. Ottieni Token ​

3. Ottieni Tassi ​

4. Quota Tasso di Exchange ​

5. Crea Exchange ​

6. Verifica Stato Exchange ​

Valori di stato ​

Riprova bump ​

7. Verifica Più Exchange ​

API degli Exchange 📝

Introduzione

Endpoint

1. Ottieni Catene

2. Ottieni Token

3. Ottieni Tassi

4. Quota Tasso di Exchange

5. Crea Exchange

6. Verifica Stato Exchange

Valori di stato

Riprova bump

7. Verifica Più Exchange